-
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
Changes from 13 commits
7d745d5
95a5d2d
5cfe61b
d9dde5a
134ff6e
ecb5a2e
debb526
1d5d698
33e876c
07be3e3
274119f
0c00f0f
6ef7dfd
6f071f3
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,29 @@ | ||
name: Docs | ||
|
||
on: | ||
push: | ||
branches: | ||
- main | ||
|
||
jobs: | ||
run: | ||
runs-on: ubuntu-latest | ||
steps: | ||
- uses: actions/checkout@v3 | ||
- name: Set up Python 3.11 | ||
uses: actions/setup-python@v4 | ||
with: | ||
python-version: 3.11 | ||
- name: Install dependencies | ||
run: | | ||
python -m pip install --upgrade pip | ||
pip install hatch | ||
- name: Generate Docs | ||
run: | | ||
hatch run generate-docs | ||
- name: Deploy Docs | ||
uses: JamesIves/github-pages-deploy-action@v4.4.1 | ||
with: | ||
clean: false | ||
branch: gh-pages | ||
folder: docs/_build |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -5,3 +5,4 @@ example/.outpack/index/outpack.rds | |
example/draft/ | ||
.idea | ||
/dist | ||
docs/_build |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
# Code examples | ||
|
||
Giving a short explanation here for function: | ||
|
||
(add_function)= | ||
## Add Function | ||
|
||
```python | ||
def add(x, y): | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 commentThe 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 commentThe 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! |
||
return x + y | ||
``` | ||
|
||
just like normal markdown baby | ||
|
||
```{warning} | ||
Easy there buckaroo | ||
``` | ||
|
||
```{error} | ||
No can do | ||
``` | ||
|
||
```{note} | ||
For your information | ||
``` |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,48 @@ | ||
# Configuration file for the Sphinx documentation builder. | ||
# | ||
# For the full list of built-in configuration values, see the documentation: | ||
# https://www.sphinx-doc.org/en/master/usage/configuration.html | ||
|
||
# -- Project information ----------------------------------------------------- | ||
# 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 commentThe 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 commentThe reason will be displayed to describe this comment to others. Learn more. done |
||
author = "Rich FitzJohn" | ||
release = "0.0.1" | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. this would ideally reflect the number in There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. done |
||
|
||
# -- General configuration --------------------------------------------------- | ||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration | ||
|
||
extensions = [ | ||
"sphinx_rtd_theme", | ||
"autoapi.extension", | ||
"myst_parser", | ||
"sphinx.ext.autosectionlabel", | ||
"sphinx_copybutton", | ||
] | ||
|
||
autoapi_dirs = ["../src"] | ||
autoapi_options = [ | ||
"members", | ||
"undoc-members", | ||
"show-inheritance", | ||
"show-module-summary", | ||
"special-members", | ||
"imported-members", | ||
] | ||
|
||
copybutton_prompt_text = ( | ||
r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: " | ||
) | ||
copybutton_prompt_is_regexp = True | ||
|
||
templates_path = ["_templates"] | ||
exclude_patterns = [] | ||
|
||
|
||
# -- Options for HTML output ------------------------------------------------- | ||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output | ||
|
||
html_theme = "sphinx_rtd_theme" | ||
html_static_path = ["_static"] |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,18 @@ | ||
# Welcome to outpack-py's documentation! | ||
|
||
```{toctree} | ||
:maxdepth: 2 | ||
:caption: 'Contents:' | ||
|
||
readme | ||
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 commentThe 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 commentThe 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 There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. yep MyST is all .md files |
||
|
||
Also inserting a reference to a function defined in the code file [here](add_function). | ||
|
||
Alternative way of referencing is {ref}`Add Function` (each section has an automatic ref generated for it, | ||
it matches the name of the section). | ||
|
||
We can also link a document, here I will link {doc}`readme` |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
```{include} ../README.md | ||
:relative-images: | ||
``` |
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