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
Documentation #33
Comments
The big bit of work there is the "Functionality documentation", but from what I can see you have most of this in the doc strings (which look good). One way to use these is with pydoc (scripting something to run "pydoc -w $file" on each python file will generate a load of HTML documentation). However, I suspect there are much better ways to do this via http://docs.readthedocs.io |
Also, a very useful form of documentation is an executable notebook. Once the packaging is done this is easy to set up via binder. Basically you can build a URL that embeds the notebook location on github, following that link gives the reader a running notebook to play with. |
Have Sphinx up and running, auto-building docs from docstrings. Issues with the mantle_timestepping module as this contains relative imports (it imports core module and mantle properties module); however, on the to-do list is changing the way this function uses the core object (moving instantiation out of the timestepping function and instead feeding in a calleable argument), and will do similar with the mantle_properties object (improves modularity) too, which results in not requiring relative imports. Can look into fixing the relative imports issue more if when all the refactoring and tidying up is finished and it ends up still being a problem. Have not yet set up a github workflow to rebuild docs when changes are pushed to the repo, and haven't yet linked it to read the docs. Need to rewrite/add detail to some doc strings, and remove comments that are accidentally being pulled into the documentation. |
Also sphinx has an extension that builds a html gallery of examples from a defined directory of python scripts; can point this to jupyter nb files so they are included tidily in the documentation (as well as having a live version on binder) - https://sphinx-gallery.github.io/stable/index.html |
Nice! It looks like that's how Matplotlib makes their examples. |
Doc issues for pytesimal package importsWhen certain packages (including pytesimal) are imported, sphinx autodoc fails, because these packages haven't been added to it's requirements.txt. Commenting out Going to use their |
I'm putting any minor documentation issues on this branch: https://github.com/murphyqm/pytesimal/tree/amw-docs - I'll generate a pull request once I think I've found them all. |
Probably need to go through all the docstrings to check:
We probably also need to think about how to explain the coupling in a useful way ... this will be needed in the paper and (possibly) in an example. |
Just combing through docstrings now, adding units. Does the below sound sensible for specifying call signatures for the material properties in the
|
Do you need to pass in objects here, or could you pass in the method itself as a callable? Looking at If you need the whole object inside discretisation I would change |
Add full documentation including community guidelines, list here.
The text was updated successfully, but these errors were encountered: