Fixing Doc Build Warnings (#1736)

* updating installation page * adding debug config page * fixing highlight warnings * making images work * fixing block formatting * fixing docstring for api * removing changelog update instructions * fixing more warnings * deleting scripts docs * formatting index * deleting section also in git_links.inc * putting html_theme_options back in * clearning warnings in cmfgen.py * fixing docstrings for AtomData api * including full file name to exclude ads notebook * explaining why code was commented out * formatting with black
tardis-sn · Jul 20, 2021 · dfdbf04 · dfdbf04
1 parent fed40d7
commit dfdbf04
Show file tree

Hide file tree

Showing 16 changed files with 59 additions and 51 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -45,8 +45,8 @@
 
 # -- General configuration ----------------------------------------------------
 
-# By default, highlight as Python 3.
-highlight_language = "python3"
+# By default, code is not highlighted.
+highlight_language = "none"
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = "1.2"
@@ -60,10 +60,11 @@
 exclude_patterns.append("_templates")
 exclude_patterns.append("_build")
 exclude_patterns.append("**.ipynb_checkpoints")
+exclude_patterns.append("research/research_done_using_TARDIS/ads.ipynb")
 
 # This is added to the end of RST files - a good place to put substitutions to
 # be used globally.
-rst_epilog += """
+rst_epilog = """
 """
 
 extensions = [
@@ -164,7 +165,7 @@
 # Add any paths that contain custom themes here, relative to this directory.
 # To use a different custom theme, add the directory containing the theme.
 import sphinx_rtd_theme
-html_theme_path = sphinx_rtd_theme.get_html_theme_path()
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes. To override the custom theme, set this to the
@@ -173,9 +174,9 @@
 
 
 html_theme_options = {
-    "logotext1": "tardis",  # white,  semi-bold
-    "logotext2": "",  # orange, light
-    "logotext3": ":docs"   # white,  light
+#    "logotext1": "tardis",  # white,  semi-bold
+#    "logotext2": "",  # orange, light
+#    "logotext3": ":docs"   # white,  light
     }
 
 

diff --git a/docs/credits.rst b/docs/credits.rst
@@ -22,6 +22,7 @@ following paragraph to the Acknowledgement section:
     development of \\textsc{tardis} received support from GitHub, the Google Summer of Code
     initiative, and from ESA's Summer of Code in Space program. \\textsc{tardis} is a fiscally
     sponsored project of NumFOCUS. \\textsc{tardis} makes extensive use of Astropy and Pyne.
+
 If you use any of the full relativity treatments or use TARDIS for modelling
 Type II supernovae, also add `Spectral modeling of type II supernovae. I. Dilution factors <https://ui.adsabs.harvard.edu/abs/2019A%26A...621A..29V>`_ 
 to the Acknowledgement.

diff --git a/docs/development/azure_links.inc b/docs/development/azure_links.inc
@@ -11,7 +11,5 @@
 .. _update it manually: https://docs.microsoft.com/en-us/azure/devops/repos/git/import-git-repository?view=azure-devops#what-if-my-source-repository-contains-git-lfs-objects
 .. _error 413: https://developercommunity.visualstudio.com/content/problem/867488/git-lfs-push-got-413-error.html
 
-.. |emdash| unicode:: U+02014
-
 .. vim: ft=rstS
 
diff --git a/docs/development/code_quality.rst b/docs/development/code_quality.rst
@@ -82,12 +82,16 @@ Some of the important formatting conventions to note here are:
 
 - Variable, module, function, and class names should be written between single back-ticks \` \`.
 
-- In the above example the return variable and type is specified. For the "Returns" section, the type must always be stated, even if the variable is not. The "Returns" section should follow the format of: ::
+- In the above example the return variable and type is specified. For the "Returns" section, the type must always be stated, even if the variable is not. The "Returns" section should follow the format of:
 
+.. code-block:: python
+    
+    """
     Returns
     -------
     (`optional variable name` : )type
         (optional descriptor)
+    """
 
 - The "Returns" section should not be included if the function/module/class does not have a return value(s).
 

diff --git a/docs/development/continuous_integration.rst b/docs/development/continuous_integration.rst
@@ -21,13 +21,13 @@ nor storage.
 
 **To clone this repository:**
 
-::
+.. code-block:: bash
 
   git clone https://[email protected]/tardis-sn/TARDIS/_git/tardis-refdata
 
 **To download a LFS file trough HTTPS:**
 
-::
+.. code-block:: none
 
   https://dev.azure.com/tardis-sn/TARDIS/_apis/git/repositories/tardis-refdata/items?path=atom_data/kurucz_cd23_chianti_H_He.h5&resolveLfs=true
 
@@ -61,14 +61,16 @@ Triggers
 First thing to do is telling the pipeline when it should run. In
 Azure, *trigger* (also known as the CI trigger) sets up the pipeline
 to run every time changes are pushed to a branch.
-::
+
+.. code-block:: yaml
 
   trigger: 
     - master
 
 If some trigger is not specified then the default configuration
 is assumed.
-::
+
+.. code-block:: yaml
 
   trigger:
     branches:
@@ -86,7 +88,8 @@ commits to a pull request.
 
 If you want to run a pipeline only manually set both triggers to
 *none*.
-::
+
+.. code-block:: yaml
 
   trigger: none
 
@@ -132,7 +135,7 @@ Define variables
 
 Usually, we define variables at the top of the YAML file.
 
-::
+.. code-block:: yaml
 
   variables:
     my.var: 'foo'
@@ -149,7 +152,8 @@ and *stage* level.
 
 Also, variables are available to scripts through environment variables.
 The name is upper-cased and ``.``  is replaced with ``_``. For example
-::
+
+.. code-block:: yaml
 
   variables:
     my.var: 'foo'
@@ -160,7 +164,8 @@ The name is upper-cased and ``.``  is replaced with ``_``. For example
 
 To set a variable from a script task, use the ``task.setvariable`` logging
 command.
-::
+
+.. code-block:: yaml
 
   steps:
 
@@ -198,7 +203,9 @@ Jobs
 You can organize your pipeline into jobs. Every pipeline has at least one job.
 A job is a series of steps that run sequentially as a unit. In other words,
 a job is the smallest unit of work that can be scheduled to run.
-::
+
+
+.. code-block:: yaml
 
   jobs:
   - job: myJob
@@ -328,7 +335,7 @@ compares against latest reference data stored in ``tardis-refdata`` repository.
 you want to compare two different labels (SHAs, branches, tags, etc.) uncomment and
 set the ``ref1.hash`` and ``ref2.hash`` variables in 
 ``.github/workflows/compare-refdata.yml`` on your pull request. For example:
-::
+.. code-block:: yaml
 
   ref1.hash: 'upstream/pr/11'
   ref2.hash: 'upstream/master'

diff --git a/docs/development/git_workflow.rst b/docs/development/git_workflow.rst
@@ -187,11 +187,6 @@ given in the following sections.
 * As the code is converging to a final state, ensure your
   documentation follows the guidelines (see :ref:`documentation-guidelines`).
 
-* Once your code is ready to be accepted, please add an entry to the changelog
-  (see :ref:`changelog-format`). If you're not sure where to put this, please
-  at least suggest a brief (one or two sentence) description of your change so
-  that another developer can add it to the changelog.
-
 This way of working helps to keep work well-organized, with readable history.
 This in turn makes it easier for project maintainers (that might be you) to
 see what you've done and why you did it.

diff --git a/docs/index.rst b/docs/index.rst
@@ -15,6 +15,7 @@ TARDIS Core Package Documentation
 .. image:: graphics/tardis_banner.svg
 
 |
+
 TARDIS is an open-source Monte Carlo radiative-transfer spectral synthesis code
 for 1D models of supernova ejecta. It is designed for rapid spectral modelling
 of supernovae. It is developed and maintained by a :ref:`multi-disciplinary team <team>`

diff --git a/docs/installation.rst b/docs/installation.rst
@@ -6,9 +6,8 @@ Installation
 
 Before installing TARDIS, please check its :ref:`requirements
 <requirements_label>`. We provide :ref:`instructions <anaconda_inst_label>` for installing TARDIS using 
-Anaconda. If you encounter problems, consult the
-:ref:`troubleshooting <troubleshooting_inst_label>` section. Once you have
-installed TARDIS, check out the "Using TARDIS" section (in sidebar) for instructions regarding how to perform simple TARDIS calculations.
+Anaconda. Once you have installed TARDIS, check out the "Input/Output" section (in sidebar) for instructions
+regarding how to perform simple TARDIS calculations.
 
 .. _requirements_label:
 

diff --git a/docs/io/configuration/components/atomic/atomic_data_description.rst b/docs/io/configuration/components/atomic/atomic_data_description.rst
@@ -224,9 +224,3 @@ ion number and level number. The `pandas <https://pandas.pydata.org/>`_ framewor
 use :py:class:`pandas.MultiIndex`, :py:class:`pandas.Series` and :py:class:`pandas.DataFrame`.
 
 TO BE BETTER DOCUMENTED ...
-
-
-
-
-
-.. automodapi:: tardis.io.atomic
diff --git a/docs/io/configuration/components/debug.rst b/docs/io/configuration/components/debug.rst
@@ -0,0 +1,9 @@
+*******************
+Debug Configuration
+*******************
+
+Coming soon!
+
+.. jsonschema:: schemas/debug.yml
+
+.
diff --git a/docs/io/configuration/components/index.rst b/docs/io/configuration/components/index.rst
@@ -37,4 +37,5 @@ in the base schema, and important information about the configuration is linked
     plasma
     models/index
     montecarlo
-    spectrum
+    spectrum
+    debug
diff --git a/docs/outdated/old_gui.rst b/docs/outdated/old_gui.rst
@@ -102,7 +102,7 @@ When you launch the GUI, the first screen that you see will be something like th
 You can inspect the plot of shells on this window and use the toggle button to change between the 
 plot of dilution factor and the radiation temperature in shells.
 
-.. image:: images/OpeningScreen.png
+.. image:: ../io/images/OpeningScreen.png
     :width: 900
 
 Shell Info
@@ -112,7 +112,7 @@ similar strategy in the tables that appear to bring up the ion and level populat
 The snapshot below shows all the tables that you can bring up by successively clicking the horizontal
 table headers. This feature is not supported at the moment.
 
-.. image:: images/ShellInfo.png
+.. image:: ../io/images/ShellInfo.png
     :width: 900
 
 Line Info
@@ -121,5 +121,5 @@ If you switch to the spectrum tab, you can see the spectrum plot and a button to
 Once again, you can double-click the table headers to get further information. The snapshot below
 shows all the tables that you can bring up in this window. This feature is not supported at the moment.
 
-.. image:: images/LineInfo.png
+.. image:: ../io/images/LineInfo.png
     :width: 900
diff --git a/docs/scripts/index.rst b/docs/scripts/index.rst
diff --git a/tardis/io/atom_data/base.py b/tardis/io/atom_data/base.py
@@ -111,8 +111,13 @@ class AtomData(object):
 
     Methods
     -------
-    from_hdf
-    prepare_atom_data
+    from_hdf:
+        Function to read the atom data from a TARDIS atom HDF Store
+    prepare_atom_data:
+        Prepares the atom data to set the lines, levels and if requested macro
+        atom data.  This function mainly cuts the `levels` and `lines` by
+        discarding any data that is not needed (any data for atoms that are not
+        needed
 
     Notes
     -----

diff --git a/tardis/io/logger/logger.py b/tardis/io/logger/logger.py
@@ -75,6 +75,7 @@ def logging_state(log_state, tardis_config, specific):
     Called from within run_tardis()
     Configured via functional arguments passed through run_tardis() - log_state & specific
     Configured via YAML parameters under `debug` section - logging_level & specific_logging
+
     Parameters
     ----------
     log_state: str

diff --git a/tardis/scripts/cmfgen2tardis.py b/tardis/scripts/cmfgen2tardis.py
@@ -4,10 +4,10 @@
 import numpy as np
 import pandas as pd
 
-from tardis.atomic import AtomData
+from tardis.io.atom_data import AtomData
 
-
-atomic_dataset = AtomData.from_hdf5()
+# The from_hdf() method requires an argument, so the line below doesn't work
+# atomic_dataset = AtomData.from_hdf()
 
 
 def get_atomic_number(element):
Original file line number	Diff line number	Diff line change
Expand Up		@@ -224,9 +224,3 @@ ion number and level number. The `pandas <https://pandas.pydata.org/>`_ framewor
		use :py:class:`pandas.MultiIndex`, :py:class:`pandas.Series` and :py:class:`pandas.DataFrame`.

		TO BE BETTER DOCUMENTED ...





		.. automodapi:: tardis.io.atomic