Skip to content

Commit

Permalink
Merge pull request #951 from wkerzendorf/docs/clean_up
Browse files Browse the repository at this point in the history
Documentation restructure
  • Loading branch information
wkerzendorf authored Jul 22, 2019
2 parents cee6c0d + 18ab9f3 commit edf98ae
Show file tree
Hide file tree
Showing 108 changed files with 1,810 additions and 217 deletions.
10 changes: 6 additions & 4 deletions docs/atomic/atomic_data.rst
Original file line number Diff line number Diff line change
@@ -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
16 changes: 11 additions & 5 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 = {
Expand All @@ -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
Expand All @@ -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'
Expand All @@ -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
Expand Down
9 changes: 7 additions & 2 deletions docs/configuration/configuration.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
====================

Expand Down Expand Up @@ -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
4 changes: 2 additions & 2 deletions docs/configuration/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
Original file line number Diff line number Diff line change
Expand Up @@ -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


File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
6 changes: 3 additions & 3 deletions docs/running_tests.rst → docs/development/running_tests.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
File renamed without changes.
File renamed without changes.
78 changes: 51 additions & 27 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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

====
Expand Down
28 changes: 17 additions & 11 deletions docs/installation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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::

Expand All @@ -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

Expand All @@ -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::
Expand All @@ -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)
===========================

Expand Down
File renamed without changes.
File renamed without changes.
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. _abundancecust:

*************************************
Using a custom stratified composition
*************************************
Expand Down
File renamed without changes.
Loading

0 comments on commit edf98ae

Please sign in to comment.