diff --git a/.github/workflows/docs-release.yml b/.github/workflows/docs-release.yml index 450b6795..dd439461 100644 --- a/.github/workflows/docs-release.yml +++ b/.github/workflows/docs-release.yml @@ -1,5 +1,6 @@ name: Docs Build on: + # push: branches: - develop @@ -7,6 +8,8 @@ on: - 'arlunio/**' - 'docs/**' - '.github/workflows/docs-release.yml' + # + # pull_request: branches: - develop @@ -14,11 +17,15 @@ on: - 'arlunio/**' - 'docs/**' - '.github/workflows/docs-release.yml' + # jobs: + # Build: runs-on: ubuntu-latest + # steps: + # - uses: actions/checkout@v1 - name: Setup Python uses: actions/setup-python@v1 @@ -32,12 +39,31 @@ jobs: python -m pip install --upgrade pip python -m pip install -e .[doc] python -m pip install -r docs/requirements.txt + # + # - name: Build Docs run: | + + version=$(cat arlunio/_version.py | sed 's/.*"\(.*\)"/\1/') + towncrier --date 'Unreleased' --version "v${version}" --yes + + latest=$(curl -s "https://api.github.com/repos/swyddfa/arlunio/releases" | jq -r '.[0].tag_name') + export VERSION="$latest" + cd docs make html + # + + # + - name: Publish Artifact + uses: actions/upload-artifact@v1.0.0 + with: + name: 'docs' + path: docs/_build + # + # - name: Deploy uses: JamesIves/github-pages-deploy-action@releases/v3 with: @@ -46,4 +72,5 @@ jobs: BRANCH: gh-pages FOLDER: docs/_build/html TARGET_FOLDER: docs/ - if: github.event_name != 'pull_request' \ No newline at end of file + if: github.event_name != 'pull_request' + # diff --git a/CHANGES.rst b/CHANGES.rst index b0824585..da415401 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,8 +1,8 @@ v0.0.6 - 2020-04-18 -=================== +------------------- Features --------- +^^^^^^^^ - Introduce the concept of operators. Operators are definitions that can provide implementations of the arithmetic operators in Python like :code:`+` and @@ -15,7 +15,7 @@ Features Docs ----- +^^^^ - Added some documentation around the CI build for the blog. Also updated the blog build to run every day. (`#177 `_) @@ -25,7 +25,7 @@ Docs Misc ----- +^^^^ - Fix handling of multiple notebooks in :code:`clean-notebook.sh` and add VSCode tasks to aid with tutorial development (`#205 `_) diff --git a/blog/gallery.py b/blog/gallery.py index 0cad1a87..dd4bf0ad 100644 --- a/blog/gallery.py +++ b/blog/gallery.py @@ -170,7 +170,6 @@ def find_image(candidates: Dict[str, arlunio.Image]) -> arlunio.Image: The process for discovering images is as follows: - If there is only a single image in the namespace then we'll use that. - - If there is more than one image in the namespace, but there is one called 'image' then we'll use that. """ diff --git a/docs/conf.py b/docs/conf.py index 724c23d9..003662d7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,8 +12,6 @@ # import os -import arlunio - # -- Project information ----------------------------------------------------- project = "Arlunio" @@ -21,7 +19,19 @@ author = "Swyddfa Developers" # The full version, including alpha/beta/rc tags -version = arlunio.__version__ +version = None + +if "VERSION" in os.environ: + version = os.environ["VERSION"] + +if version is None: + try: + import arlunio + + version = arlunio.__version__ + except Exception: + version = "latest" + release = version diff --git a/docs/contributing/ci/blog-release.rst b/docs/contributing/ci/blog-release.rst index 5c53e196..afd20b3e 100644 --- a/docs/contributing/ci/blog-release.rst +++ b/docs/contributing/ci/blog-release.rst @@ -7,7 +7,7 @@ arlunio website. Currently this is only composed of the gallery. Triggers -------- -This action is triggered when ever a commit has been made to the :code:`develop` +This action is triggered whenever a commit has been made to the :code:`develop` branch within the :code:`blog/` directory so that new additions are published immediately. @@ -82,7 +82,7 @@ Delpoy Blog ^^^^^^^^^^^ Finally, if this is not a PR build, we publish the built site to our -:code:`gh-pages` branch using the `JamesIves/github-pages-deploy-action`_. +:code:`gh-pages` branch using `JamesIves/github-pages-deploy-action`_. .. literalinclude:: ../../../.github/workflows/blog-release.yml :language: yaml diff --git a/docs/contributing/ci/docs-release.rst b/docs/contributing/ci/docs-release.rst new file mode 100644 index 00000000..e9d19d0a --- /dev/null +++ b/docs/contributing/ci/docs-release.rst @@ -0,0 +1,103 @@ +Documentation Release +===================== + +This action is responsible for building and deploying the documentation which +currently sits alongside the gallery in our Github Pages instance. + +Triggers +-------- + +This action is triggered whenever a commit has been made to the :code:`develop` +branch within the :code:`docs/` or :code:`arlunio/` directories. This means the +documentation is updated to always align with the bleeding edge version of the +codebase. Since we don't currently have a stable released version this is +sufficient for now, though may need to be revised at some point in the future. + +.. literalinclude:: ../../../.github/workflows/docs-release.yml + :language: yaml + :dedent: 2 + :start-after: # + :end-before: # + +It's also configured to run on any pull request that affects the paths relevant +to ensure that changes do not break the build. + +.. literalinclude:: ../../../.github/workflows/docs-release.yml + :language: yaml + :dedent: 2 + :start-after: # + :end-before: # + + +Jobs +---- + +.. literalinclude:: ../../../.github/workflows/docs-release.yml + :language: yaml + :dedent: 2 + :start-after: # + :end-before: # + +Steps +----- + +Setup +^^^^^ + +Setup for this job is fairly standard in that we checkout the repository and get +ourselves setup with a Python version. The only interesting thing to note is +that alongside the dependencies listed in :code:`docs/requirements.txt` we also +need to install :code:`arlunio` itself since it's used to build some aspects of +the documentation. + +.. literalinclude:: ../../../.github/workflows/docs-release.yml + :language: yaml + :dedent: 4 + :start-after: # + :end-before: # + +Build Docs +^^^^^^^^^^ + +Since the documentation is built using Sphinx it follows standard practice for +the most part. However before running the Sphinx build we: + +- Use towncrier to update the changelog with details of anything that will be + coming up in the next release. +- Fetch the latest release from Github so we can set the appropriate version + number in Sphinx + +.. literalinclude:: ../../../.github/workflows/docs-release.yml + :language: yaml + :dedent: 4 + :start-after: # + :end-before: # + +Publish Build Artifact +^^^^^^^^^^^^^^^^^^^^^^ + +So that it's easy to inspect the final build of the documentation if required we +also publish the :code:`docs/_build` directory as a build artifact. + +.. literalinclude:: ../../../.github/workflows/docs-release.yml + :language: yaml + :dedent: 4 + :start-after: # + :end-before: # + + +Deploy Docs +^^^^^^^^^^^ + +Finally assuming the docs have been built successfully and this is not a PR +build, we deploy the result to Github Pages using +`JamesIves/github-pages-deploy-action`_. + +.. literalinclude:: ../../../.github/workflows/docs-release.yml + :language: yaml + :dedent: 4 + :start-after: # + :end-before: # + + +.. _JamesIves/github-pages-deploy-action: https://github.com/JamesIves/github-pages-deploy-action diff --git a/docs/contributing/ci/index.rst b/docs/contributing/ci/index.rst index 0ad0394a..df3d0eab 100644 --- a/docs/contributing/ci/index.rst +++ b/docs/contributing/ci/index.rst @@ -9,6 +9,7 @@ the actions that are defined and how they work. :maxdepth: 1 blog-release + docs-release python-linting python-pr-builds python-release diff --git a/docs/requirements.txt b/docs/requirements.txt index f07244de..c98fb6af 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,3 @@ sphinx>=2.0.0 -sphinx_rtd_theme \ No newline at end of file +sphinx_rtd_theme +towncrier diff --git a/pyproject.toml b/pyproject.toml index be6e10f0..42a09e15 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -24,11 +24,11 @@ lines_between_types = 1 multi_line_output = 3 [tool.towncrier] -package = "arlunio" filename = "CHANGES.rst" directory = "changes/" title_format = "{version} - {project_date}" issue_format = "`#{issue} `_" +underlines = ["-", "^", "\""] [[tool.towncrier.type]]