< ^ >

Softwave docu using Sphinx

Creating the new docs of ngstrefftz I used Sphinx. You can find the docs of ngstrefftz here: docs

To build docs using Sphinx you first need to

pip install sphinx

and get your project a docs folder

mkdir docs

Sphinx offers a sphinx-quickstart which will auto-generate some files and folders for you, but essentially you need a conf.py and an index.rst. Once you have those, you can build your html docu using

sphinx-build -b html . _build

The config file

The conf.py should at least contain the following:

# -- Project information -----------------------------------------------------
project = 'Projectname'
copyright = 'Year, Name'
author = 'Name'
release = v0.0.0

# -- General configuration ---------------------------------------------------
extensions = []

templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

language = 'hi'

# -- Options for HTML output -------------------------------------------------
html_theme = 'alabaster'
html_static_path = ['_static']

More on the config is given here and different sphinx themes can be found here

I wanted to use my jupyter notebooks and some python code with sphinx. Sphinx can include jupyter notebook as seperate html pages, some python code can be included in the documentation inline and is run when the docu is generated. I use the following extensions to do that

extensions = ["sphinx.ext.autodoc",
           "sphinx.ext.mathjax",
           "sphinx.ext.todo",
           "sphinx.ext.githubpages",
           "IPython.sphinxext.ipython_console_highlighting",
           "IPython.sphinxext.ipython_directive",
           "jupyter_sphinx",
           "nbsphinx",
           "m2r2",
           "sphinxemoji.sphinxemoji",
]

some of which need to be installed using pip. m2r2 loves to create some mess with the dependencies, so take care and be sure to save your requirements once everything is running. Here are mine.

There are a bunch of additional settings for sphinx and also for each package, for the notebooks I use

## Run notebook configuration
# The template used when exporting from nbconvert
#   full  - Outputs the full HTML document [Default]
#   basic - Outputs a single div (with no additional resources)
run_notebook_export_template = 'basic'  # Default: 'full'

# Display the source links to the generated evaluated files
run_notebook_display_source_links = False  # Default: True

# Whether or not to evaluate the notebooks prior to embedding them
evaluate_notebooks = True  # Default: True

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

## Set and exclude paths
templates_path = ['_templates']
html_static_path = ['_static']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'paper','env']

One can further customize the looks of the html output

html_theme = 'alabaster'
html_theme_options = {
    'fixed_sidebar':True,
    'font_size':10
}
html_sidebars = {
   'index': [
        'about.html',
        'localtoc.html',
        # 'relations.html',
       ],
   '**': ['about.html',
          'localtoc.html',
       ],
}

The index file

You can write the index file in markdown of reStructuredText. I was not familiar with rst, but why not learn something new while learning something new.. surely this type of recursion has no confusing side effects.

This is a header
========================================

This is a smaller header
----------------------------------------

Commands and special environments are started with .. command:: and need to be indented. For example, you can use LaTeX math

.. math::

    \newcommand{\Lap}{\Delta} 
    \begin{align*} \begin{split}
        \begin{cases}
        -\Lap u = 0 &\text{ in } \Omega, \\
        u=g &\text{ on } \partial \Omega,
        \end{cases}
    \end{split} \end{align*}

of python, where it is possible to hide in- or output

.. jupyter-execute::
    :hide-output:
    :hide-code:

    from ngstrefftz import *

Documentation for a function or class is generated like so

.. autofunction:: ngstrefftz.TWave

.. autoclass:: ngstrefftz.TrefftzTents

   .. automethod:: Propagate
   .. automethod:: SetInitial
   .. automethod:: SetBoundaryCF