From 28280c34ac1087d1007447c4efa99c336cf793e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Steven!=20Ragnar=C3=B6k?= Date: Fri, 9 Aug 2024 13:03:31 -0700 Subject: [PATCH 1/4] Update for local documentation building. I had to comment out the example intersphinx mapping as None is apparently no longer a valid map value. I also attempted to use extras_require to specify documentation dependencies which are probably incomplete but it was enough to build on my machine. --- doc/conf.py | 2 +- setup.py | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index 583cc4d4c..a18ea3f99 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -232,4 +232,4 @@ # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'http://docs.python.org/': None} +# intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/setup.py b/setup.py index 9f4a17d79..fa3d3d93b 100644 --- a/setup.py +++ b/setup.py @@ -22,6 +22,10 @@ 'flake8-quotes', 'pytest', ], + 'doc': [ + 'catkin_sphinx', + 'sphinx' + ], }, 'author': 'Tully Foote, Ken Conley', 'author_email': 'tfoote@osrfoundation.org', From 9043f6c30c4c8c7bb35f2a93616a75a24ead84dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Steven!=20Ragnar=C3=B6k?= Date: Mon, 19 Aug 2024 20:16:54 -0700 Subject: [PATCH 2/4] Add earthly build configuration for building docs. I prefer the now acceptable build.earth filename over for the Filefile-style Earthfile. Along with the build.earth I've also included a .earthlyignore file which uses the same format as a [.dockerignore] file. Although we are not creating distributable images ignoring spurious files in the docker context helps cut down on cache misses invalidating dependency layers in the build. [.dockerignore]: https://docs.docker.com/build/concepts/context/#dockerignore-files --- .earthlyignore | 19 +++++++++++++++++++ build.earth | 35 +++++++++++++++++++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 .earthlyignore create mode 100644 build.earth diff --git a/.earthlyignore b/.earthlyignore new file mode 100644 index 000000000..fab2394f8 --- /dev/null +++ b/.earthlyignore @@ -0,0 +1,19 @@ +# https://docs.docker.com/build/concepts/context/#dockerignore-files +# Unlike .gitignore files directories are not ignored at all layers by default. +# The **/ prefix will make a pattern behave like a .gitignore pattern and apply +# in any directory, including the root. +**/*.pyc +**/.direnv/ +**/.envrc +**/.git/ +**/.github/ +**/.pytest_cache/ +**/.ruff_cache/ +**/__pycache__/ +**/_build/ +**/build/ +**/deb_dist/ +**/dist/ +**/rosdep.egg-info/ +**/rosdep_modules.egg-info/ +**/target/ diff --git a/build.earth b/build.earth new file mode 100644 index 000000000..e932e204b --- /dev/null +++ b/build.earth @@ -0,0 +1,35 @@ +VERSION 0.8 + +build: + FROM docker.io/library/python:3.12 + RUN mkdir -p /src || true + COPY --dir doc src test \ + CHANGELOG.rst \ + Makefile \ + README.md \ + rosdoc.yaml \ + setup.cfg \ + setup.py \ + stdeb.cfg \ + /src/rosdep + WORKDIR /src/rosdep + RUN pip install -e . + +testdeps: + FROM +build + RUN pip install .[test] + +test: + # TODO tests aren't passing in context. + FROM +testdeps + RUN pytest test + +docdeps: + FROM +build + RUN pip install .[doc] + +doc: + FROM +docdeps + WORKDIR /src/rosdep/doc + RUN make html + SAVE ARTIFACT _build/html AS LOCAL doc/_build/html From 996815f61b7ab779f61e05de718e66990687f7c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Steven!=20Ragnar=C3=B6k?= Date: Mon, 19 Aug 2024 20:55:16 -0700 Subject: [PATCH 3/4] Add GitHub Actions workflow to deploy documentation to GitHub Pages. --- .github/workflows/doc.yaml | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 .github/workflows/doc.yaml diff --git a/.github/workflows/doc.yaml b/.github/workflows/doc.yaml new file mode 100644 index 000000000..4b83c0921 --- /dev/null +++ b/.github/workflows/doc.yaml @@ -0,0 +1,37 @@ +--- +name: Doc build +on: + push: + branches: ['main', 'docdeps'] + +jobs: + build: + runs-on: ubuntu-22.04 + steps: + - uses: actions/checkout@v4 + - uses: earthly/actions-setup@v1 + - name: Build documentation + run: | + earthly --ci --output +doc + upload: + needs: build + runs-on: ubuntu-22.04 + steps: + - name: Upload build for GitHub Pages + uses: actions/upload-pages-artifact@v3 + with: + path: doc/_build/html + deploy: + permissions: + contents: read + id-token: write + pages: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + needs: upload + runs-on: ubuntu-22.04 + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 From b82031f095dc8b8074bed36176f538fc3eeced81 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Steven!=20Ragnar=C3=B6k?= Date: Mon, 19 Aug 2024 21:04:52 -0700 Subject: [PATCH 4/4] Separate jobs run in separate contexts. I thought that workflows were isolated but jobs were not. Ah well. --- .github/workflows/doc.yaml | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/.github/workflows/doc.yaml b/.github/workflows/doc.yaml index 4b83c0921..e715c8e2a 100644 --- a/.github/workflows/doc.yaml +++ b/.github/workflows/doc.yaml @@ -13,10 +13,6 @@ jobs: - name: Build documentation run: | earthly --ci --output +doc - upload: - needs: build - runs-on: ubuntu-22.04 - steps: - name: Upload build for GitHub Pages uses: actions/upload-pages-artifact@v3 with: @@ -29,7 +25,7 @@ jobs: environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} - needs: upload + needs: build runs-on: ubuntu-22.04 steps: - name: Deploy to GitHub Pages