Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add sphinx doc #202

Open
wants to merge 23 commits into
base: master
Choose a base branch
from

Conversation

KybernetikJo
Copy link
Contributor

@KybernetikJo KybernetikJo commented Jul 26, 2023

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 KybernetikJo marked this pull request as ready for review August 17, 2023 19:49
@KybernetikJo
Copy link
Contributor Author

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

doc/conf.py Outdated
Comment on lines 13 to 16
project = 'Slycot'
copyright = '2023, Slycot Developers'
author = 'Slycot Developers'
release = '0.6'
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can this be automated to look at the git tag?

Copy link
Contributor Author

@KybernetikJo KybernetikJo Aug 24, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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))

.. autosummary::
:toctree: generated/

ab01nd
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@KybernetikJo KybernetikJo Aug 24, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Collaborator

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

@KybernetikJo
Copy link
Contributor Author

KybernetikJo commented Aug 26, 2023

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants