Merge pull request sirocco-rt#1076 from smangham/issue1075-sphinx-pyp…

…rogs Document `py_progs` using Sphinx
smangham · May 24, 2024 · 7374525 · 7374525
2 parents dd77a1a + 418c42c
commit 7374525
Show file tree

Hide file tree

Showing 122 changed files with 2,105 additions and 977 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -19,9 +19,12 @@ formats: all
 # Set the OS, Python version and other tools you might need
 build:
   os: ubuntu-22.04
+  apt_packages:
+    - libhdf4-dev
   tools:
     python: "3.12"
 
+
 # Optionally set the version of Python and requirements required to build your docs
 python:
   install:

diff --git a/docs/sphinx/requirements.txt b/docs/sphinx/requirements.txt
@@ -1,5 +1,5 @@
-sphinx
-sphinx-issues
+sphinx==5.3.0
+sphinx-issues==4.1.0
 ipython
 nbsphinx
 sphinx-rtd-theme
@@ -11,3 +11,4 @@ scipy
 sqlalchemy
 jinja2==3.0.3
 sphinx_gallery
+pyhdf
diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py
@@ -35,12 +35,15 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.ifconfig',
     'sphinx.ext.githubpages',
+    'sphinx.ext.autosummary',
     'sphinx.ext.todo',
     'sphinx.ext.autosectionlabel',
     'sphinx_issues',
     'nbsphinx',
     'IPython.sphinxext.ipython_console_highlighting',
     'sphinx.ext.autodoc',
+    'sphinx.ext.autodoc.typehints',
+    'sphinx.ext.napoleon',
     "sphinx_gallery.load_style",
 ]
 
@@ -74,17 +77,17 @@
 
 # General information about the project.
 project = 'python'
-copyright = '2018-2023, Knox Long, Christian Knigge, Stuart Sim, Nick Higginbottom, James Matthews, Sam Mangham, Edward Parkinson, Mandy Hewitt'
+copyright = '2018-2024, Knox Long, Christian Knigge, Stuart Sim, Nick Higginbottom, James Matthews, Sam Mangham, Edward Parkinson, Mandy Hewitt'
 author = 'Knox Long, Christian Knigge, Stuart Sim, Nick Higginbottom, James Matthews, Sam Mangham, Edward Parkinson, Mandy Hewitt'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '86'
+version = '88'
 # The full version, including alpha/beta/rc tags.
-release = '86g'
+release = '88a'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -101,6 +104,9 @@
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
+# Whether to include type hints in the doc, and where
+autodoc_typehints = 'both'
+
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -167,8 +173,11 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'python.tex', 'python Documentation',
-     'Knox Long, Christian Knigge, Stuart Sim, Nick Higginbottom, James Matthews, Sam Mangham, Edward Parkinson, Mandy Hewitt', 'manual'),
+    (
+        master_doc, 'python.tex', 'python Documentation',
+        author,
+        'manual'
+     ),
 ]
 
 # -- Options for manual page output ---------------------------------------

diff --git a/docs/sphinx/source/config.py b/docs/sphinx/source/config.py
diff --git a/docs/sphinx/source/examples/demo-models/quasar/quasar.rst b/docs/sphinx/source/examples/demo-models/quasar/quasar.rst
@@ -7,7 +7,9 @@ This particular document focuses on Model A from M20. As with most of the demo m
 
 The wind is equatorial, and illuminated by an isotropic SED. 
 
-.. todo:: more description needed
+.. note::
+
+    more description needed
 
 Important Parameters
 ============================
@@ -42,4 +44,4 @@ Outputs
 ============================
 
 References
-============================
+============================
diff --git a/docs/sphinx/source/meta.rst b/docs/sphinx/source/meta.rst
@@ -290,7 +290,7 @@ The above link contains full documentation of the commands. A module in py_progs
 
 .. code :: rst
 
-    .. automodule:: py_read_output.py
+    .. automodule:: py_read_output
         :members:
 
 For this to work properly, docstrings have to be in a reasonable rst format. We might consider using the `napoleon extension <https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html>`_ if this is not to our taste.

diff --git a/docs/sphinx/source/plotting/plot_spectrum.ipynb b/docs/sphinx/source/plotting/plot_spectrum.ipynb
diff --git a/docs/sphinx/source/plotting/plot_wind.ipynb b/docs/sphinx/source/plotting/plot_wind.ipynb
diff --git a/docs/sphinx/source/py_progs.rst b/docs/sphinx/source/py_progs.rst
@@ -1,21 +1,21 @@
 Python Scripts
-##############
+################################
 
-There are several `Python` (the scripting language) scripts written to prepare input for
+There are several `Python` scripts written to prepare input for
 and analyse the output of *python* (the C code).
 
-Some of the more useful scripts/modules are documented below. Alternatively, you can generate documentation 
-for all the scripts by navigating to :code:`docs/pydocs` and running :code:`write_docs.py`. The resulting output file can be found `here <../../pydocs/doc_index.html>`_.
+Some of the more useful scripts/modules are documented below.
+Alternatively, you can generate documentation for all the scripts by navigating to :code:`docs/pydocs` and running :code:`write_docs.py`.
+The resulting output file can be found `here <../../pydocs/doc_index.html>`_.
 
 .. admonition :: Warning to user
 
-    The scripts documented here form an incomplete and inhomogenous list, in the sense that they have been developed by different people at different times and do not fit nicely together as a single python package. Some of the scripts should still be useful, particularly if you consult example notebookes, but use with caution!
+    The scripts documented here form an incomplete and inhomogenous list, in the sense that they have been developed by different people at different times and do not fit nicely together as a single python package.
+    Some of the scripts should still be useful, particularly if you consult example notebookes, but use with caution!
 
-.. todo:: Finish adding modules below.
 
 .. toctree::
+    :maxdepth: 2
+    :glob:
 
-   py_progs/plotting
-   py_progs/testing
-   py_progs/utilities
-   py_progs/py4py
+    py_progs/*
diff --git a/docs/sphinx/source/py_progs/MakeMacro.rst b/docs/sphinx/source/py_progs/MakeMacro.rst
@@ -86,5 +86,12 @@ without the -guess option to produce a final set of files
 **Note that at present the routine does not handle the collisional x-sections, though this should be straightforward to add**
 
 
+API Documentation
+=================
 
+.. autosummary::
+    :toctree: MakeMacro
 
+    MakeMacro
+    MacroCombine
+    RedoPhot
diff --git a/docs/sphinx/source/py_progs/MakeMacro.sphinx_cannot_doc b/docs/sphinx/source/py_progs/MakeMacro.sphinx_cannot_doc
@@ -0,0 +1 @@
+Macro2Simple
diff --git a/docs/sphinx/source/py_progs/MakeMacro/MacroCombine.rst b/docs/sphinx/source/py_progs/MakeMacro/MacroCombine.rst
@@ -0,0 +1,37 @@
+MacroCombine
+============
+
+.. automodule:: MacroCombine
+
+
+
+
+
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+
+      add_gtot
+      plot_xsec
+      read_phot
+      redo_lines
+      redo_phot
+      reweight
+      steer
+      write_phot
+      xguess
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/sphinx/source/py_progs/MakeMacro/MakeMacro.rst b/docs/sphinx/source/py_progs/MakeMacro/MakeMacro.rst
@@ -0,0 +1,38 @@
+MakeMacro
+=========
+
+.. automodule:: MakeMacro
+
+
+
+
+
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+
+      calculate_oscillator_strength
+      doit
+      get_collisions
+      get_f
+      get_levels
+      get_lines
+      get_phot
+      make_phot
+      print_elvlc
+      write_phot
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/sphinx/source/py_progs/MakeMacro/RedoPhot.rst b/docs/sphinx/source/py_progs/MakeMacro/RedoPhot.rst
@@ -0,0 +1,34 @@
+RedoPhot
+========
+
+.. automodule:: RedoPhot
+
+
+
+
+
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+
+      extrap
+      plot_phot
+      read_phot
+      redo_one
+      steer
+      write_phot_tab
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/sphinx/source/py_progs/development.rst b/docs/sphinx/source/py_progs/development.rst
@@ -0,0 +1,33 @@
+Developer Tools
+---------------
+
+Several scripts have been written to assist in developing and documenting **Python**.
+
+
+Documentation
+=============
+
+.. autosummary::
+    :toctree: development
+
+    autogenerate_parameter_docs
+    autogenerate_rtd_pages
+    dox
+    dox_check
+
+
+
+Development
+===========
+
+.. autosummary::
+    :toctree: development
+
+    add_param
+    update_param
+    run_indent
+    init_extern
+    make_rtheta
+    pf_check
+    CheckAtomic
+    retro
diff --git a/docs/sphinx/source/py_progs/development/CheckAtomic.rst b/docs/sphinx/source/py_progs/development/CheckAtomic.rst
@@ -0,0 +1,35 @@
+CheckAtomic
+===========
+
+.. automodule:: CheckAtomic
+
+
+
+
+
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+
+      analyze_lines
+      doit
+      get_element_table
+      get_ion_tab
+      get_level_tab
+      get_line_tab
+      xread
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/sphinx/source/py_progs/development/add_param.rst b/docs/sphinx/source/py_progs/development/add_param.rst
@@ -0,0 +1,32 @@
+add\_param
+==========
+
+.. automodule:: add_param
+
+
+
+
+
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+
+      do_one
+      doit
+      read_file
+      read_table
+
+
+
+
+
+
+
+
+
+
+
+
+