Reorganizing docs for website release (#1835)

* restructuring docs for new website release * moving quickstart * removing unnecessary images * fixing quickstart links * fixing tardis example symlink in development directory * fixing hyperlinks * changing grid page name and linking website * Jaladh's comments
tardis-sn · Dec 10, 2021 · 48f56f1 · 48f56f1
1 parent 59ff077
commit 48f56f1
Show file tree

Hide file tree

Showing 68 changed files with 122 additions and 500 deletions.
diff --git a/.gitignore b/.gitignore
@@ -20,7 +20,7 @@ MANIFEST
 # Sphinx
 docs/api
 docs/_build
-docs/ZENODO.rst
+docs/resources/ZENODO.rst
 docs/tutorials.rst
 docs/io/configuration/components/models/converters/density_parse.csv
 docs/io/configuration/components/models/converters/abund_parse.csv

diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
diff --git a/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
diff --git a/docs/conf.py b/docs/conf.py
@@ -63,7 +63,7 @@
 exclude_patterns.append("_templates")
 exclude_patterns.append("_build")
 exclude_patterns.append("**.ipynb_checkpoints")
-exclude_patterns.append("research/research_done_using_TARDIS/ads.ipynb")
+exclude_patterns.append("resources/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.
@@ -345,7 +345,7 @@ def generate_ZENODO(app):
     """Creating ZENODO.rst
     Adapted from: https://astrodata.nyc/posts/2021-04-23-zenodo-sphinx/"""
     CONCEPT_DOI = "592480"  # See: https://help.zenodo.org/#versioning
-    zenodo_path = pathlib.Path("ZENODO.rst")
+    zenodo_path = pathlib.Path("resources/ZENODO.rst")
 
     try:
         headers = {"accept": "application/x-bibtex"}

diff --git a/docs/contributing/CHANGELOG.md b/docs/contributing/CHANGELOG.md
@@ -0,0 +1 @@
+../../CHANGELOG.md
diff --git a/docs/contributing/CONTRIBUTING.md b/docs/contributing/CONTRIBUTING.md
@@ -0,0 +1 @@
+../../CONTRIBUTING.md
diff --git a/docs/development/azure_links.inc → .../contributing/development/azure_links.inc b/docs/development/azure_links.inc → .../contributing/development/azure_links.inc
diff --git a/docs/development/code_quality.rst → ...contributing/development/code_quality.rst b/docs/development/code_quality.rst → ...contributing/development/code_quality.rst
diff --git a/docs/development/continuous_integration.rst → ...ng/development/continuous_integration.rst b/docs/development/continuous_integration.rst → ...ng/development/continuous_integration.rst
diff --git a/docs/development/debug_numba.rst → .../contributing/development/debug_numba.rst b/docs/development/debug_numba.rst → .../contributing/development/debug_numba.rst
diff --git a/docs/development/developer_faq.rst → ...ontributing/development/developer_faq.rst b/docs/development/developer_faq.rst → ...ontributing/development/developer_faq.rst
diff --git a/.../development/documentation_guidelines.rst → .../development/documentation_guidelines.rst b/.../development/documentation_guidelines.rst → .../development/documentation_guidelines.rst
@@ -18,17 +18,17 @@ When making or adding changes to the functionality of an aspect of TARDIS, an ``
 RST Documentation
 -----------------
 
-Documentation not featuring interactive code examples is written in Sphinx's reStructuredText (see `here <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_). Files written in reStructuredText have a ``.rst`` file extension, and are then built as HTML filed by Sphinx during the documentation build. Only the RST file, not the built HTML file, are committed to the repository. Documentation should be clear and concise. See :doc:`../io/visualization/using_widgets` as a good example of an RST-generated page.
+Documentation not featuring interactive code examples is written in Sphinx's reStructuredText (see `here <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_). Files written in reStructuredText have a ``.rst`` file extension, and are then built as HTML filed by Sphinx during the documentation build. Only the RST file, not the built HTML file, are committed to the repository. Documentation should be clear and concise. See :doc:`../../io/visualization/using_widgets` as a good example of an RST-generated page.
 
 
 IPYNB Documentation
 -------------------
 
-Often, code examples can help explain concepts better. The TARDIS utilizes `Jupyter notebooks <https://jupyter.org/>`_ (``.ipynb`` file extension) to demonstrate features of the code package within our documentation. See :doc:`../quickstart/quickstart` or :doc:`../physics/montecarlo/initialization` for good examples.
+Often, code examples can help explain concepts better. The TARDIS utilizes `Jupyter notebooks <https://jupyter.org/>`_ (``.ipynb`` file extension) to demonstrate features of the code package within our documentation. See :doc:`../../quickstart` or :doc:`../../physics/montecarlo/initialization` for good examples.
 
 TARDIS uses the `nbsphinx <https://nbsphinx.readthedocs.io/>`_ extension to turn these notebooks into HTML pages in the documentation. During a documentation build, nbsphinx runs all notebooks in the documentation with cleared output and places their output in the HTML. **Thus, notebook output must always be cleared before it is submitted** to ensure that the notebooks are run by nbsphinx. Running these notebooks during the documentation build helps ensure that the documentation is kept up-to-date, as notebook output will reflect the current state of the TARDIS code. Additionally, if updates in the code are inconsistent with the documentation, the documentation build will return an error, alerting TARDIS developers to the inconsistency.
 
-An added benefit of IPYNB documentation is the ability to have interactive tutorials. All notebooks in the TARDIS documentation feature a button at the top encouraging users to launch the interactive version of the notebook (see the previously mentioned examples). This directs users to the TARDIS repository on `Binder <https://mybinder.org/>`_, where the notebook can be run using an online Jupyter kernel. Additionally, all notebooks in the Input/Output section of the documentation are automatically linked to on the :doc:`../tutorials` page.
+An added benefit of IPYNB documentation is the ability to have interactive tutorials. All notebooks in the TARDIS documentation feature a button at the top encouraging users to launch the interactive version of the notebook (see the previously mentioned examples). This directs users to the TARDIS repository on `Binder <https://mybinder.org/>`_, where the notebook can be run using an online Jupyter kernel. Additionally, all notebooks in the Input/Output section of the documentation are automatically linked to on the :doc:`../../tutorials` page.
 
 
 Including Your Page in the TARDIS Documentation
@@ -37,8 +37,8 @@ Including Your Page in the TARDIS Documentation
 Whether your page is written in reStructuredText or as a Jupyter notebook, it must be included in the TARDIS documentation. This has three steps:
 
 1. Determine the appropriate location for the page within the documentation. Feel free to reach out to someone in the TARDIS collaboration for help with this step.
-2. Place your file in the corresponding directory in the ``docs/`` directory of the repository. For example, the :doc:`../io/visualization/using_widgets` is a subpage of "Visualization Tools and Widgets" under the Input/Output section of the documentation, so it is placed in ``docs/io/visualization/``.
-3. Include your file in the/a `toctree <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree>`_ of the corresponding ``index.rst``. For example, :doc:`../io/visualization/using_widgets` was included in a toctree of ``docs/io/visualization/index.rst``.
+2. Place your file in the corresponding directory in the ``docs/`` directory of the repository. For example, the :doc:`../../io/visualization/using_widgets` is a subpage of "Visualization Tools and Widgets" under the Input/Output section of the documentation, so it is placed in ``docs/io/visualization/``.
+3. Include your file in the/a `toctree <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree>`_ of the corresponding ``index.rst``. For example, :doc:`../../io/visualization/using_widgets` was included in a toctree of ``docs/io/visualization/index.rst``.
 
 .. note::
 

diff --git a/docs/development/git_links.inc → docs/contributing/development/git_links.inc b/docs/development/git_links.inc → docs/contributing/development/git_links.inc
diff --git a/docs/development/git_workflow.rst → ...contributing/development/git_workflow.rst b/docs/development/git_workflow.rst → ...contributing/development/git_workflow.rst
@@ -29,7 +29,7 @@ Preparation and Working with Git
 ================================
 
 In this document, we refer to the TARDIS ``master`` branch as the *trunk*. The first step is to setup up a python environment. We recommend using
-Anaconda for this purpose; refer to our :doc:`Installation guide <../installation>` which covers this topic.
+Anaconda for this purpose; refer to our :doc:`Installation guide <../../installation>` which covers this topic.
 
 .. _forking:
 

diff --git a/docs/development/images/Bootcamp-Fork.png → ...ting/development/images/Bootcamp-Fork.png b/docs/development/images/Bootcamp-Fork.png → ...ting/development/images/Bootcamp-Fork.png
diff --git a/docs/development/images/branch_dropdown.png → ...ng/development/images/branch_dropdown.png b/docs/development/images/branch_dropdown.png → ...ng/development/images/branch_dropdown.png
diff --git a/docs/development/images/pull_button.png → ...buting/development/images/pull_button.png b/docs/development/images/pull_button.png → ...buting/development/images/pull_button.png
diff --git a/docs/development/images/variables.png → ...ributing/development/images/variables.png b/docs/development/images/variables.png → ...ributing/development/images/variables.png
diff --git a/docs/development/index.rst → docs/contributing/development/index.rst b/docs/development/index.rst → docs/contributing/development/index.rst
diff --git a/docs/development/integration.yml → .../contributing/development/integration.yml b/docs/development/integration.yml → .../contributing/development/integration.yml
diff --git a/docs/development/issues.rst → docs/contributing/development/issues.rst b/docs/development/issues.rst → docs/contributing/development/issues.rst
diff --git a/docs/development/known_projects.inc → ...ntributing/development/known_projects.inc b/docs/development/known_projects.inc → ...ntributing/development/known_projects.inc
diff --git a/docs/development/links.inc → docs/contributing/development/links.inc b/docs/development/links.inc → docs/contributing/development/links.inc
diff --git a/docs/development/matterbridge.inc → ...contributing/development/matterbridge.inc b/docs/development/matterbridge.inc → ...contributing/development/matterbridge.inc
diff --git a/docs/development/matterbridge.rst → ...contributing/development/matterbridge.rst b/docs/development/matterbridge.rst → ...contributing/development/matterbridge.rst
diff --git a/...g/cpu_threads_dict_128_threads_1_node.csv → ...g/cpu_threads_dict_128_threads_1_node.csv b/...g/cpu_threads_dict_128_threads_1_node.csv → ...g/cpu_threads_dict_128_threads_1_node.csv
diff --git a/docs/development/profiling/index.rst → ...tributing/development/profiling/index.rst b/docs/development/profiling/index.rst → ...tributing/development/profiling/index.rst
diff --git a/...lopment/profiling/profiling_example.ipynb → ...lopment/profiling/profiling_example.ipynb b/...lopment/profiling/profiling_example.ipynb → ...lopment/profiling/profiling_example.ipynb
diff --git a/docs/contributing/development/profiling/tardis_example.yml b/docs/contributing/development/profiling/tardis_example.yml
@@ -0,0 +1 @@
+../../../tardis_example.yml
diff --git a/docs/development/profiling/tardis_prof.png → ...ing/development/profiling/tardis_prof.png b/docs/development/profiling/tardis_prof.png → ...ing/development/profiling/tardis_prof.png
diff --git a/.../profiling/tardis_profiling_threads.ipynb → .../profiling/tardis_profiling_threads.ipynb b/.../profiling/tardis_profiling_threads.ipynb → .../profiling/tardis_profiling_threads.ipynb
diff --git a/...iling/threads_dict_128_threads_1_node.csv → ...iling/threads_dict_128_threads_1_node.csv b/...iling/threads_dict_128_threads_1_node.csv → ...iling/threads_dict_128_threads_1_node.csv
diff --git a/docs/development/running_tests.rst → ...ontributing/development/running_tests.rst b/docs/development/running_tests.rst → ...ontributing/development/running_tests.rst
diff --git a/docs/development/this_project.inc → ...contributing/development/this_project.inc b/docs/development/this_project.inc → ...contributing/development/this_project.inc
diff --git a/docs/development/update_refdata.rst → ...ntributing/development/update_refdata.rst b/docs/development/update_refdata.rst → ...ntributing/development/update_refdata.rst
@@ -36,7 +36,7 @@ If you think your could be dealing with scenario B, then:
 .. note::
 
     - If you don't have enough privileges to run the pipelines, tag a TARDIS developer capable of doing so.
-    - If any of these two pipelines fail, please tag the :ref:`CI/CD responsible <team>`.
+    - If any of these two pipelines fail, please tag a `TARDIS team member <https://tardis-sn.github.io/team/community_roles/>`_ responsible for CI/CD.
 
 If everything went well, the reference data will have been updated by the TARDIS bot and the commit
 message should include the pull request number that triggered the update.

diff --git a/docs/roadmap.rst → docs/contributing/roadmap.rst b/docs/roadmap.rst → docs/contributing/roadmap.rst
diff --git a/docs/development/profiling/tardis_example.yml b/docs/development/profiling/tardis_example.yml
diff --git a/docs/graphics/esa.png b/docs/graphics/esa.png
diff --git a/docs/graphics/github.png b/docs/graphics/github.png
diff --git a/docs/graphics/google.png b/docs/graphics/google.png
diff --git a/docs/graphics/numfocus.png b/docs/graphics/numfocus.png
diff --git a/docs/index.rst b/docs/index.rst
@@ -18,10 +18,15 @@ 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 :ref:`multi-disciplinary team <team>`
+of supernovae. It is developed and maintained by a 
+`multi-disciplinary team <https://tardis-sn.github.io/team/community_roles/>`_
 including software engineers, computer scientists, statisticians,
 and astrophysicists.
 
+The tardis package is the core package provided by the TARDIS Project. To learn
+more about the complete project, other packages it provides, and the community
+behind it, please check the `project website <https://tardis-sn.github.io>`_.
+
 If you use this code for any publications or presentations please follow our
 citation guidelines in :ref:`tardiscredits`.
 
@@ -43,13 +48,12 @@ Mission Statement
     research and science reproducibility.*
 
 
-
 .. toctree::
     :maxdepth: 2
     :hidden:
 
     installation
-    quickstart/quickstart
+    quickstart
     tutorials
     API <api/modules>
 
@@ -76,41 +80,25 @@ Mission Statement
     physics/spectrum/index
 
 
-.. toctree::
-    :maxdepth: 2
-    :caption: Research with TARDIS
-    :hidden:
-
-    Overview <research/index>
-
-
-.. toctree::
-    :maxdepth: 2
-    :caption: Team & Credits
-    :hidden:
-
-    team_and_governance/index
-    credits
-    Code of Conduct <CODE_OF_CONDUCT.md>
-    sponsors
-
-
 .. toctree::
     :maxdepth: 2
     :caption: Contributing to TARDIS
     :hidden:
 
-    CONTRIBUTING.md
-    development/index
-    CHANGELOG.md
-    roadmap
+    contributing/CONTRIBUTING.md
+    contributing/development/index
+    contributing/CHANGELOG.md
+    contributing/roadmap
 
 
 .. toctree::
-    :caption: References
+    :caption: Other Resources
     :hidden:
-
-    zreferences
+
+    resources/credits
+    resources/research_done_using_TARDIS/research_papers
+    resources/code_comparison/index
+    resources/zreferences
 
 
 .. toctree::
@@ -119,9 +107,3 @@ Mission Statement
     :hidden:
 
     outdated/index
-
-----
-News
-----
-
-.. include:: news.rst
diff --git a/docs/io/configuration/example.rst b/docs/io/configuration/example.rst
@@ -7,7 +7,7 @@ TARDIS Example Configuration
 The simple and fast TARDIS setup is provided by ``tardis_example.yml`` which
 may be obtained `here
 <https://raw.githubusercontent.com/tardis-sn/tardis/master/docs/tardis_example.yml>`_. We suggest every new user of TARDIS to run this
-setup first, which can be done using the :doc:`quickstart guide <../../quickstart/quickstart>`.
+setup first, which can be done using the :doc:`quickstart guide <../../quickstart>`.
 
 It calculates a spectrum for a Type Ia supernova model 13 days after explosion,
 requesting a total output luminosity of