From c9460f2d5f62d339948ac0f915467b2aa664fadb Mon Sep 17 00:00:00 2001 From: Daniel Weindl Date: Mon, 13 Jan 2025 20:56:50 +0100 Subject: [PATCH] Build documentation via tox (#36) To build the documentation, run `tox -e doc`. Build the documentation on GHA. --- .github/workflows/ci.yaml | 28 ++++++++++++++++++++++++++++ doc/.gitignore | 1 + {docs => doc}/Makefile | 0 {docs => doc}/changelog.rst | 0 {docs => doc}/conf.py | 2 +- {docs => doc}/contributing.rst | 0 {docs => doc}/faq.rst | 0 {docs => doc}/index.rst | 0 {docs => doc}/installation.rst | 0 {docs => doc}/license.rst | 0 {docs => doc}/make.bat | 0 {docs => doc}/preparation.rst | 0 {docs => doc}/usage.rst | 0 pyproject.toml | 13 ++++++++++++- 14 files changed, 42 insertions(+), 2 deletions(-) create mode 100644 doc/.gitignore rename {docs => doc}/Makefile (100%) rename {docs => doc}/changelog.rst (100%) rename {docs => doc}/conf.py (96%) rename {docs => doc}/contributing.rst (100%) rename {docs => doc}/faq.rst (100%) rename {docs => doc}/index.rst (100%) rename {docs => doc}/installation.rst (100%) rename {docs => doc}/license.rst (100%) rename {docs => doc}/make.bat (100%) rename {docs => doc}/preparation.rst (100%) rename {docs => doc}/usage.rst (100%) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 36ed6b9..5ebf28c 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -115,3 +115,31 @@ jobs: echo $! > ccompass_pid.txt sleep 10 kill $(cat ccompass_pid.txt) + + test_docs: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.12' + + - name: Cache tox + uses: actions/cache@v4 + with: + path: ~/.cache/tox + key: ${{ runner.os }}-tox-${{ hashFiles('pyproject.toml') }} + restore-keys: | + ${{ runner.os }}-tox- + + - name: Install dependencies + run: | + pip install tox + + - name: Build documentation + run: | + tox -e doc diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..e35d885 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +_build diff --git a/docs/Makefile b/doc/Makefile similarity index 100% rename from docs/Makefile rename to doc/Makefile diff --git a/docs/changelog.rst b/doc/changelog.rst similarity index 100% rename from docs/changelog.rst rename to doc/changelog.rst diff --git a/docs/conf.py b/doc/conf.py similarity index 96% rename from docs/conf.py rename to doc/conf.py index 9172bce..c483c20 100644 --- a/docs/conf.py +++ b/doc/conf.py @@ -24,4 +24,4 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output html_theme = "alabaster" -html_static_path = ["_static"] +# html_static_path = ["_static"] diff --git a/docs/contributing.rst b/doc/contributing.rst similarity index 100% rename from docs/contributing.rst rename to doc/contributing.rst diff --git a/docs/faq.rst b/doc/faq.rst similarity index 100% rename from docs/faq.rst rename to doc/faq.rst diff --git a/docs/index.rst b/doc/index.rst similarity index 100% rename from docs/index.rst rename to doc/index.rst diff --git a/docs/installation.rst b/doc/installation.rst similarity index 100% rename from docs/installation.rst rename to doc/installation.rst diff --git a/docs/license.rst b/doc/license.rst similarity index 100% rename from docs/license.rst rename to doc/license.rst diff --git a/docs/make.bat b/doc/make.bat similarity index 100% rename from docs/make.bat rename to doc/make.bat diff --git a/docs/preparation.rst b/doc/preparation.rst similarity index 100% rename from docs/preparation.rst rename to doc/preparation.rst diff --git a/docs/usage.rst b/doc/usage.rst similarity index 100% rename from docs/usage.rst rename to doc/usage.rst diff --git a/pyproject.toml b/pyproject.toml index a9643e2..ec20dd9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -27,4 +27,15 @@ requires-python = ">=3.10" ccompass = "ccompass.CCMPS:main" [project.optional-dependencies] -dev = ["pre-commit>=3"] +dev = ["pre-commit>=3", "tox"] +doc = ["sphinx", "sphinx-rtd-theme"] + +[tool.tox] +requires = ["tox>=4.19"] +env_list = ["doc"] + +[tool.tox.env.doc] +description = "Build the documentation" +extras = ["doc"] +commands = [["sphinx-build", "-W", "-b", "html", "doc/", "doc/_build/html"]] +working_directory = "doc"