Add documentation pipeline #32
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #32 +/- ##
==========================================
Coverage 100.00% 100.00%
==========================================
Files 43 43
Lines 2481 2787 +306
Branches 371 439 +68
==========================================
+ Hits 2481 2787 +306 ☔ View full report in Codecov by Sentry. |
|
|
||
| on: | ||
| push: | ||
| branches: |
There was a problem hiding this comment.
this should run on prs too, but just not update the gh-pages branch. See https://github.com/mrc-ide/hipercow/blob/main/.github/workflows/pkgdown.yaml for how we do this on R builds.
| ## Add Function | ||
|
|
||
| ```python | ||
| def add(x, y): |
There was a problem hiding this comment.
this code is not actually run yet, right? I could have syntactically nonsense code and that'd be fine? Do we have a ticket for working out how to integrate quarto or similar?
There was a problem hiding this comment.
yep can make a ticket, so before doing this PR i had a play around with code executing packages, sphinx doctest unfortunately will not be good for us because while it does execute code, it does not attach the output to the next line. There is one other package I found called autorun and that is like having a python console and will have the output of the code on the next line but each code block is like a different python console so no setup code. I had a look at the autorun source code and it doesnt seem super difficult, I think we should just make our own code executing sphinx extension
There was a problem hiding this comment.
Did a quick demo, see #34 for a automatic code execution docs example and let me know what you think!
docs/conf.py
Outdated
| # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information | ||
|
|
||
| project = "outpack-py" | ||
| copyright = "2024, Rich FitzJohn" |
There was a problem hiding this comment.
Imperial holds our copyright; see LICENSE.txt; copy that over
docs/conf.py
Outdated
| project = "outpack-py" | ||
| copyright = "2024, Rich FitzJohn" | ||
| author = "Rich FitzJohn" | ||
| release = "0.0.1" |
There was a problem hiding this comment.
this would ideally reflect the number in src/outpack/__about__.py; that can be imported. Similarly if we could get the project slurped in we'd be able to copy this file around between projects easily
| code | ||
| ``` | ||
|
|
||
| % uses MyST markdown format https://jupyterbook.org/en/stable/content/myst.html |
There was a problem hiding this comment.
if we're using ReST 🤮 the extension should be .rst not .md
There was a problem hiding this comment.
Looks like this is using MyST, which sounds like it is slightly different? And they use .md in their docs. https://myst-parser.readthedocs.io/en/latest/intro.html#write-a-markdown-document
There was a problem hiding this comment.
yep MyST is all .md files
| code | ||
| ``` | ||
|
|
||
| % uses MyST markdown format https://jupyterbook.org/en/stable/content/myst.html |
There was a problem hiding this comment.
Looks like this is using MyST, which sounds like it is slightly different? And they use .md in their docs. https://myst-parser.readthedocs.io/en/latest/intro.html#write-a-markdown-document
This should be the full pipeline for adding, generating and deploying documentation. I configured the workflow file temporarily to upload documentation from pull-requests as well (to test this branch out) but have removed it so now only push to main will generate and deploy documentation. See an example of the workflow result on https://mrc-ide.github.io/outpack-py/.
To test this out:
hatch run generate-docsdocs/_build/index.htmlin your favourite browser. Can runfirefox docs/_build/index.htmlif you want.I have written some small examples of how to write certain things in the docs. Next to add will probably be code running and showing the output of the code running in the docs. However, this might need to be hand rolled. I have tried a couple sphinx integrations but they only allow you to run in python console and there wasn't any scope for setup code before the example and shared functions within the same file.