Add sphinx doc

[KybernetikJo]

This PR adds a sphinx documentation. The doc includes an introduction, API reference, developer info and examples.

• Introduction
• API reference
  • autodoc slycot.<>
  • autodoc slycot._wrapper.<>
  • SLICOT help as link
• Developer Guide / Contribution Guide
  • github slycot, pull request
  • Guide to create a wrapper, f2py, .pyf, numpydoc (not sure how detailed it will be)
• Examples
  • Python scripts (some example)
  • Python scripts (more or better Examples, maybe)
  • Jupyter notebooks
  • Jupyter notebooks (more or better Examples, maybe)
• "Slycot Analyzer"
  • inspect slicot fortran.f files
  • inspect slicot help files
  • inspect slycot routines
  • inspect slycot._wrapper rountines
  • compare slycot implemented rountines with hellp
• Github Action
  • check all added rountines are included in the sphinx doc (as suggested by @bnavigator )

[KybernetikJo]

From my point of view, this version would be ready for merging.

[bnavigator]

Can this be automated to look at the git tag?

[KybernetikJo]

I could use the code from python-control. Would that be enough?

# Version information - read from the source code
import re

# Get the version number for this commmit (including alpha/beta/rc tags)
release = re.sub('^v', '', os.popen('git describe').read().strip())

# The short X.Y.Z version
version = re.sub(r'(\d+\.\d+\.\d+(.post\d+)?)(.*)', r'\1', release)

print("version %s, release %s" % (version, release))

[bnavigator]

So wee need to add entries here for every additional wrapper? Better write a check that we don't forget anything.

[KybernetikJo]

Good point. I also thought about that.

There is a python script /doc/create_names_for_reference.py that generates all routine names of
slycot and slycot._wrapper.

I think there are 2 options:

1. a script that compares the output from the script above with the routine names found in slycot_outer.rst and slycot_inner.rst.
2. a script that generates the whole files of slycot_outer.rst and slycot_inner.rst.

I have to look into that.

[bnavigator]

Do we need a sphinx workflow in the .github actions in order to check results?

[KybernetikJo]

Do we need a sphinx workflow in the .github actions in order to check results?

To be honest, I don't have much experience with github actions and don't know what is possible.

Currently I'm thinking about some kind of slycot-analyzer that analyzes the slycot and slicot-reference modules, generates statistics and checks for some completeness.

I would put this "slycot-analyzer" under slycot/doc/slycot-analyzer.

github actions could call some functions of a "slycot-analyzer".

Currently there are some python/notebook files:

• doc/check_names.py
• doc/create_names_for_reference.py
• doc/source/dev/inspect_slycot.ipynb
• doc/source/dev/inspect_slicot_slycot.ipynb

For now, though, I'll focus on the docstring and numpydocs.