Skip to content

Add a workflow to build/check/upload docs. #212

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.

Sign up for GitHub

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

Open
ezio-melotti wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Add a workflow to build/check/upload docs. #212

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
41a60fb
Add a workflow to build/check/upload docs.
ezio-melotti Sep 16, 2022
1a7a9fc
Merge branch 'master' into docs-workflow
ezio-melotti May 7, 2023
caefcb1
Merge branch 'master' into docs-workflow
ezio-melotti May 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions .github/workflows/build-docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
name: Publish Docs to simoc.space

on:
push:
paths:
- 'docs/**'

@granawkins granawkins Sep 17, 2022

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

I don't think this catches changes for parts that use autodoc, because the changes would actually be in e.g. agent_model/agent_model.py. Could just build on every commit? Or maybe have a way to trigger it manually.

@ezio-melotti ezio-melotti Sep 17, 2022

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

I don't think this catches changes for parts that use autodoc,

Good point -- if the code is changed but not the doc, this won't be triggered.

Could just build on every commit?

I thought about that, but there a few (minor) downsides:

  • It's a bit wasteful to do it all the time
  • It will end up adding an irrelevant extra check to all PRs
  • I wanted to see if/how the path filtering works

Or maybe have a way to trigger it manually.

It has a manual trigger already (the workflow_dispatch below), so maybe we can just use that instead?

Another option would be to schedule e.g. weekly build, so that even if we forget to deploy manually it will be updated automatically. I have to check if it's possible to combine regular triggers with schedules though.

pull_request:
paths:
- 'docs/**'
workflow_dispatch:

jobs:
docs:
runs-on: ubuntu-latest
steps:
- name: Checkout Repository
uses: actions/checkout@v3
- name: Install SIMOC Dependencies
# these are needed for autodoc
run: |
python3 -m pip install --upgrade pip
python3 -m pip install -r requirements.txt
- name: Install Docs Dependencies
run: |
python3 -m pip install sphinx sphinx-rtd-theme sphinx-jsonschema sphinx-lint

@granawkins granawkins Sep 17, 2022

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

We have a requirements-jupyter.txt file, which includes a subset of requirements.txt needed to run + the jupyter-specific packages. Esp with a virtualenv it'd be convenient to have an "only what you need to build the docs" package list.

@ezio-melotti ezio-melotti Sep 17, 2022

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

See also my comment in the other PR.

For this workflow it doesn't matter if we install everything globally (including all the requirements.txt) since we are in a disposable env. However all the deps add up to 600MB, and if it's done in a docs-specific env it will take a lot of space.

Some options include:

  • have a single shared env for everything (docs/jupyter/etc.), which will still duplicate the deps with the docker container
  • have the deps installed globally, and only install the docs deps in the venv
  • build the docs inside the container, which already has the regular deps installed and only needs the extra docs ones

Now that I think about it, the last option might be the best one for local installations, even though it's a bit more involved.

- name: Build Docs
run: |
cd docs
make html
- name: Check Docs
run: |
sphinx-lint --enable default-role docs
- name: Upload to simoc.space
# Only upload when the workflow is triggered manually or
# when a PR that affects docs is merged on master.
# The always() ensures that this is run even if the
# sphinx-lint check failed.
if: ${{ always() && (github.event_name == 'workflow_dispatch' ||
(github.event_name == 'push' && github.ref_name == 'master')) }}
run: |
echo 'Uploading docs to simoc.space...'
ls -l docs/_build/html
# TODO: upload with SCP