Merge pull request #951 from wkerzendorf/docs/clean_up

Documentation restructure
tardis-sn · Jul 22, 2019 · edf98ae · edf98ae
2 parents cee6c0d + 18ab9f3
commit edf98ae
Show file tree

Hide file tree

Showing 108 changed files with 1,810 additions and 217 deletions.
diff --git a/docs/atomic/atomic_data.rst b/docs/atomic/atomic_data.rst
@@ -1,9 +1,11 @@
 .. _atomic-data-download:
 
-**********************
-Atomic Data for TARDIS
-**********************
+***********
+Atomic Data
+***********
+
+The Atom Database for TARDIS is generated by the Carsus package.
 
 .. toctree::
     atomic_data_description
-    current_public_table.rst
+    current_public_table
diff --git a/docs/conf.py b/docs/conf.py
@@ -36,7 +36,6 @@
     'astropy': ('http://docs.astropy.org/en/stable/', None),
     'h5py': ('http://docs.h5py.org/en/latest/', None),
     'pandas': ('http://pandas.pydata.org/pandas-docs/dev/', None),
-    'astropy': ('http://docs.astropy.org/en/stable/', None)
 }
 
 # import sphinx_bootstrap_theme
@@ -48,11 +47,12 @@
     'sphinx.ext.todo',
     'sphinx.ext.mathjax',
     'sphinx.ext.graphviz',
+    'sphinx.ext.viewcode',
     'numpydoc',
     'nbsphinx',
-    'sphinx.ext.autodoc',
     'sphinx-jsonschema',
-    'recommonmark'
+    'recommonmark',
+    'sphinxcontrib.apidoc'
 ]
 
 source_suffix = {
@@ -78,7 +78,7 @@
 templates_path = ['_templates']
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build', '_templates']
+exclude_patterns = ['_build', '_templates',  '**.ipynb_checkpoints']
 #exclude_patterns.append('_templates')
 
 # This is added to the end of RST files - a good place to put substitutions to
@@ -90,7 +90,7 @@
 
 # This does not *have* to match the package name, but typically does
 project = u'TARDIS'
-author = u'TARDIS team'
+author = u'TARDIS collaboration'
 copyright = u'2013, ' + author
 
 master_doc = 'index'
@@ -106,6 +106,12 @@
 release = tardis.__version__
 
 
+# -- APIDoc configuration -----------------------------------------------------
+apidoc_module_dir = '../tardis'
+apidoc_output_dir = 'api'
+apidoc_excluded_paths = ['*tests*', '*setup_package*']
+apidoc_separate_modules = True
+
 # -- Options for HTML output ---------------------------------------------------
 
 # A NOTE ON HTML THEMES

diff --git a/docs/configuration/configuration.rst b/docs/configuration/configuration.rst
@@ -7,8 +7,7 @@ Configuration File
 TARDIS uses the `YAML markup language <https://en.wikipedia.org/wiki/YAML>`_
 for its configuration files. There are several sections which allow different
 settings for the different aspects of the TARDIS calculation. An example
-configuration file (with a small subset of the options that can be specified) can be downloaded :download:`here
-<../examples/tardis_example.yml>`.
+configuration file (with a small subset of the options that can be specified) can be downloaded at `example_yml`_.
 
 .. warning::
     One should note that currently floats in YAML need to be specified in a special format:
@@ -24,6 +23,10 @@ can be seen here:
     The following shows all the options (and their default settings) that are available for TARDIS. No other options
     are allowed or available
 
+
+.. contents:: Overview
+    :local:
+
 Configuration Schema
 ====================
 
@@ -159,3 +162,5 @@ just an integer. Finally, the method option selects the final spectral synthesis
   interaction mode. Note also the limitations listed at the bottom of the
   dedicated page.
 
+
+.. include:: ../running/example_data.inc
diff --git a/docs/configuration/index.rst b/docs/configuration/index.rst
@@ -11,8 +11,8 @@ and pages provide more details concerning the TARDIS configuration process.
 
 
 .. toctree::
-  :maxdepth: 3
+  :maxdepth: 2
 
   configuration
   config_validator
-  read_configuration.ipynb
+  read_configuration
diff --git a/docs/workflow/azure_links.inc → docs/development/azure_links.inc b/docs/workflow/azure_links.inc → docs/development/azure_links.inc
diff --git a/docs/workflow/continuous_integration.rst → docs/development/continuous_integration.rst b/docs/workflow/continuous_integration.rst → docs/development/continuous_integration.rst
diff --git a/docs/developer_faq.rst → docs/development/developer_faq.rst b/docs/developer_faq.rst → docs/development/developer_faq.rst
diff --git a/docs/workflow/git_links.inc → docs/development/git_links.inc b/docs/workflow/git_links.inc → docs/development/git_links.inc
diff --git a/docs/workflow/git_workflow.rst → docs/development/git_workflow.rst b/docs/workflow/git_workflow.rst → docs/development/git_workflow.rst
diff --git a/docs/workflow/images/Bootcamp-Fork.png → docs/development/images/Bootcamp-Fork.png b/docs/workflow/images/Bootcamp-Fork.png → docs/development/images/Bootcamp-Fork.png
diff --git a/docs/workflow/images/branch_dropdown.png → docs/development/images/branch_dropdown.png b/docs/workflow/images/branch_dropdown.png → docs/development/images/branch_dropdown.png
diff --git a/docs/workflow/images/lock.png → docs/development/images/lock.png b/docs/workflow/images/lock.png → docs/development/images/lock.png
diff --git a/docs/workflow/images/pull_button.png → docs/development/images/pull_button.png b/docs/workflow/images/pull_button.png → docs/development/images/pull_button.png
diff --git a/docs/workflow/images/secure_file.png → docs/development/images/secure_file.png b/docs/workflow/images/secure_file.png → docs/development/images/secure_file.png
diff --git a/docs/workflow/images/variables.png → docs/development/images/variables.png b/docs/workflow/images/variables.png → docs/development/images/variables.png
diff --git a/docs/workflow/development_workflow.rst → docs/development/index.rst b/docs/workflow/development_workflow.rst → docs/development/index.rst
@@ -8,20 +8,32 @@ workflow is taken from `Astropy <http://docs.astropy.org
 /en/stable/development/workflow/development_workflow.html>`_ and credit belongs
 to the Astropy team for designing it.
 
+.. toctree::
+    :maxdepth: 2
+
+    running_tests
+    issues
 
 
 
 .. toctree::
+    :maxdepth: 2
+    :caption: Git and coding workflow
 
     git_workflow
-    release_workflow
+
 
 .. toctree::
+    :maxdepth: 2
+    :caption: TARDIS core team instructions
 
+    release_workflow
     update_refdata
+    continuous_integration
+    developer_faq
+
+
 
-.. toctree::
 
-    continuous_integration
 
 
diff --git a/docs/yml_files/integration.yml → docs/development/integration.yml b/docs/yml_files/integration.yml → docs/development/integration.yml
diff --git a/docs/issues.rst → docs/development/issues.rst b/docs/issues.rst → docs/development/issues.rst
diff --git a/docs/workflow/known_projects.inc → docs/development/known_projects.inc b/docs/workflow/known_projects.inc → docs/development/known_projects.inc
diff --git a/docs/workflow/links.inc → docs/development/links.inc b/docs/workflow/links.inc → docs/development/links.inc
diff --git a/docs/workflow/release_workflow.rst → docs/development/release_workflow.rst b/docs/workflow/release_workflow.rst → docs/development/release_workflow.rst
diff --git a/docs/running_tests.rst → docs/development/running_tests.rst b/docs/running_tests.rst → docs/development/running_tests.rst
@@ -52,7 +52,7 @@ or generate new ones.
 
 Both of of these require a configuration file for the integration tests:
 
-.. literalinclude:: yml_files/integration.yml
+.. literalinclude:: integration.yml
     :language: yaml
 
 Inside the atomic data directory there needs to be atomic data for each of
@@ -63,15 +63,15 @@ use very few packets to generate the references and thus make the process much
 faster - THIS IS ONLY FOR DEBUGGING PURPOSES. The ``-s`` option ensures that
 TARDIS prints out the progress:
 
-.. code-block::
+.. code-block:: shell
 
     > python setup.py test --args="--integration=integration.yml -m integration
     --generate-reference --less-packets"
 
 To run the test after having run the ``--generate-references`` all that is
 needed is:
 
-.. code-block::
+.. code-block:: shell
 
     > python setup.py test --args="--integration=integration.yml -m integration
     --less-packets" --remote-data

diff --git a/docs/workflow/this_project.inc → docs/development/this_project.inc b/docs/workflow/this_project.inc → docs/development/this_project.inc
diff --git a/docs/workflow/update_refdata.rst → docs/development/update_refdata.rst b/docs/workflow/update_refdata.rst → docs/development/update_refdata.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -17,63 +17,87 @@ Tardis Core Package Documentation
 
 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 multi-disciplinary team
+of supernovae. It is developed and maintained by a :ref:`multi-disciplinary team <team>`
 including software engineers, computer scientists, statisticians,
 and astrophysicists.
 
 If you use this code for any publications or presentations please follow our
 citation guidelines in :ref:`tardiscredits`
 
-User modifications and additions that lead to publications need to be handed
-back to the community by incorporating them into TARDIS.
+User modifications and additions that lead to publications **need to be handed
+back to the community** by incorporating them into TARDIS.
 Please contact the TARDIS team via the `github page
 <https://github.com/tardis-sn/tardis>`_ if you have questions or need
 assistance.
 
-============
-Using Tardis
-============
+
 
 .. toctree::
     :maxdepth: 2
+    :hidden:
 
     installation
-    CHANGELOG.md
-    quickstart
+    quickstart/quickstart
+
+
+
+.. toctree::
+    :maxdepth: 3
+    :caption: Using TARDIS
+    :hidden:
+
+
     running/index
-    examples/index
-    scripts/index
-    team
-    credits
 
-======================
-Looking under the hood
-======================
 
 .. toctree::
     :maxdepth: 2
+    :caption: The Physics of TARDIS
+    :hidden:
+
+    Physics overview <physics/index>
+    physics/plasma/index
+    physics/montecarlo/index
+
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Research with TARDIS
+    :hidden:
+
+    Overview <research/index>
+
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Team & Credits
+    :hidden:
+
+    team
+    credits
 
-    atomic/atomic_data
-    physics/index
-    montecarlo/index
 
+.. toctree::
+    :maxdepth: 2
+    :caption: Developers Guide
+    :hidden:
 
-=================
-Developing Tardis
-=================
+    development/index
+    CHANGELOG.md
 
 .. toctree::
     :maxdepth: 2
+    :caption: API
+    :hidden:
+
+    api/modules
 
-    issues
-    workflow/development_workflow
-    running_tests
 
-==========
-References
-==========
 
 .. toctree::
+    :caption: References
+    :hidden:
+
     zreferences
 
 ====

diff --git a/docs/installation.rst b/docs/installation.rst
@@ -16,19 +16,19 @@ simple TARDIS calculations.
 
 .. warning::
 
-    TARDIS is currently only compatbile with Python 2.7.
+    TARDIS is only compatbile with Python >3.6
 
 .. note::
-    We strongly recommond to install TARDIS within an Anaconda environment and
+    We strongly recommend to install TARDIS within an Anaconda environment and
     to always use the lastest github development version.
 
 Requirements
 ============
 
-You can see a list of all the requirements of TARDIS in the `environment definition file <https://raw.githubusercontent.com/tardis-sn/tardis/master/tardis_env27.yml>`_.
+You can see a list of all the requirements of TARDIS in the `environment definition file <https://raw.githubusercontent.com/tardis-sn/tardis/master/tardis_env3.yml>`_.
 
-TARDIS is using astropy's excellent installation helpers and thus uses similar
-instructions to astropy.
+TARDIS is using Astropy's excellent installation helpers and thus uses similar
+instructions to Astropy.
 
 .. _anaconda_inst_label:
 
@@ -45,13 +45,13 @@ machine. The next step is to create an environment for TARDIS that contains all
 of the necessary packages (this ensures that TARDIS requirements won't clash
 with any other python installs on disc::
 
-First, download the `environment definition file <https://raw.githubusercontent.com/tardis-sn/tardis/master/tardis_env27.yml>`_ from::
+First, download the `environment definition file <https://raw.githubusercontent.com/tardis-sn/tardis/master/tardis_env3.yml>`_ from::
 
-    https://raw.githubusercontent.com/tardis-sn/tardis/master/tardis_env27.yml
+    https://raw.githubusercontent.com/tardis-sn/tardis/master/tardis_env3.yml
 
 To create the environment, change to the directory that you downloaded the environment definition file and run::
 
-    conda env create -f tardis_env27.yml
+    conda env create -f tardis_env3.yml
 
 Then to activate this environment simply do::
 
@@ -68,7 +68,8 @@ and after you are done with TARDIS you can deactivate::
 One does not need to recreate the environment, but simply activate it every time
 TARDIS is used.
 
-Since TARDIS has reached a mature state, we recommend always installing the latest development version::
+Since TARDIS has reached a mature state, we recommend always installing the
+latest development version::
 
     pip install git+https://github.com/tardis-sn/tardis
 
@@ -78,6 +79,12 @@ Alternatively, you can manually clone our repository and install TARDIS by
     cd tardis
     python setup.py install
 
+
+.. _install_openmp:
+Enabling parallel execution with OpenMP
+---------------------------------------
+
+
 Manually, cloning the repository enables other options such as running the code in parallel (enabling OpenMP).
 In general we encourage to download the compilers from `conda` as we then can ensure that they work with TARDIS.
 Within the TARDIS conda environment do::
@@ -92,13 +99,12 @@ For Linux::
 
     conda install -c conda-forge openmp
 
-To compile TARDIS for parallel execution:
+To compile TARDIS for parallel execution::
 
     python setup.py install --with-openmp
 
 
 .. _troubleshooting_inst_label:
-
 Installation Troubles (FAQ)
 ===========================
 

diff --git a/docs/notebooks/csvy_test.ipynb → docs/models/csy/csvy_test.ipynb b/docs/notebooks/csvy_test.ipynb → docs/models/csy/csvy_test.ipynb
diff --git a/..._And_Boundary_Velocities-checkpoint.ipynb → ..._And_Boundary_Velocities-checkpoint.ipynb b/..._And_Boundary_Velocities-checkpoint.ipynb → ..._And_Boundary_Velocities-checkpoint.ipynb
diff --git a/...tom_Density_And_Boundary_Velocities.ipynb → ...tom_Density_And_Boundary_Velocities.ipynb b/...tom_Density_And_Boundary_Velocities.ipynb → ...tom_Density_And_Boundary_Velocities.ipynb
diff --git a/docs/examples/abund.dat → docs/models/examples/abund.dat b/docs/examples/abund.dat → docs/models/examples/abund.dat
diff --git a/docs/examples/abundancecust.rst → docs/models/examples/abundancecust.rst b/docs/examples/abundancecust.rst → docs/models/examples/abundancecust.rst
@@ -1,3 +1,5 @@
+.. _abundancecust:
+
 *************************************
 Using a custom stratified composition
 *************************************

diff --git a/docs/examples/abundanceuni.rst → docs/models/examples/abundanceuni.rst b/docs/examples/abundanceuni.rst → docs/models/examples/abundanceuni.rst