-
Notifications
You must be signed in to change notification settings - Fork 0
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 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
done
## Add Function | ||
|
||
```python | ||
def add(x, y): |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Imperial holds our copyright; see LICENSE.txt; copy that over
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
done
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
done
code | ||
``` | ||
|
||
% uses MyST markdown format https://jupyterbook.org/en/stable/content/myst.html |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
if we're using ReST 🤮 the extension should be .rst not .md
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yep MyST is all .md files
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good to me, nice to the see the example of the vignette like document. Would be great if we can work out a way to run that.
code | ||
``` | ||
|
||
% uses MyST markdown format https://jupyterbook.org/en/stable/content/myst.html |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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-docs
docs/_build/index.html
in your favourite browser. Can runfirefox docs/_build/index.html
if 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.