Documentation update and versioning (#627)

* Updated docs and added docs versioning - Updated full mkdocs-material dependencies. - Added mike to use docs versioning. - Fixed docstrings for new Return parsing. * Updated docs workflows - Publish dev on every dev commit. - Publish new latests version on release (using release name as tag). * Test fixes & update CHANGELOG.md * Updated docs docsdev page [skip ci] * Tidy ci-docs workflow comments [skip ci] * Remove vaex from docs dependencies - [skip ci] * Removed MarkupSafe dependency - [skip ci] * Add index.md to date exclude list - [skip ci] * Bumped minimum mkdocs-material to 8.2.4 * Updated announcement bar and CHANGELOG.md - [skip ci]
askap-vast · Mar 3, 2022 · 0600792 · 0600792
1 parent c49e1a6
commit 0600792
Show file tree

Hide file tree

Showing 34 changed files with 621 additions and 335 deletions.
diff --git a/.github/workflows/ci-docs.yml → .github/workflows/ci-docs-dev.yml b/.github/workflows/ci-docs.yml → .github/workflows/ci-docs-dev.yml
@@ -1,11 +1,11 @@
-name: ci docs
+name: ci docs dev
 
-# a merged PR will trigger a push on master so merging to master is
+# a merged PR will trigger a push on dev so merging to dev is
 # included in the event below
 on:
   push:
     branches:
-      - master
+      - dev
 jobs:
   deploy:
     runs-on: ubuntu-latest
@@ -28,4 +28,4 @@ jobs:
       - name: Install python dependencies
         run: poetry install
       - name: Build and deploy docs
-        run: poetry run mkdocs gh-deploy -m 'github action deployment' --force
+        run: poetry run mike deploy --push dev
diff --git a/.github/workflows/ci-docs-release.yml b/.github/workflows/ci-docs-release.yml
@@ -0,0 +1,32 @@
+name: ci docs release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.x
+      - uses: Gr1N/setup-poetry@v4
+      - name: Set release notes tag
+        run: |
+          export RELEASE_TAG_VERSION=${{ github.event.release.tag_name }}
+          echo "RELEASE_TAG_VERSION=${RELEASE_TAG_VERSION:1}" >> $GITHUB_ENV
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y build-essential libpq-dev libgraphviz-dev
+      - name: Cache Python dependencies
+        uses: actions/cache@v2
+        with:
+          path: ~/.cache/pypoetry/virtualenvs
+          key: ${{ runner.os }}-poetry-${{ hashFiles('poetry.lock') }}
+      - name: Install python dependencies
+        run: poetry install
+      - name: Build and deploy docs
+        run: poetry run mike deploy --push --update-aliases ${RELEASE_TAG_VERSION} latest
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 #### Added
 
+- Added documentation versioning [#627](https://github.com/askap-vast/vast-pipeline/pull/627).
 - Added a ZTF cone search button on the source detail page [#626](https://github.com/askap-vast/vast-pipeline/pull/626).
 - Added the 0-based index of each measurement to the image cutout card headers [#625](https://github.com/askap-vast/vast-pipeline/pull/625).
 - Added Bokeh hover tooltip to measurement pair graph to display pair metrics [#625](https://github.com/askap-vast/vast-pipeline/pull/625).
@@ -35,6 +36,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 #### Changed
 
+- Bumped all documentation dependancies to latest versions (incl. mkdocs-material minimum 8.2.4) [#627](https://github.com/askap-vast/vast-pipeline/pull/627).
+- Changed GitHub workflows for new documentation versioning [#627](https://github.com/askap-vast/vast-pipeline/pull/627).
 - Bumped Jinja2 to 3.0.3 to fix a Markupsafe error caused by a removed function [#634](https://github.com/askap-vast/vast-pipeline/pull/634).
 - Dependancies updated using npm audit fix (non-breaking) [#620](https://github.com/askap-vast/vast-pipeline/pull/620).
 - Refactored adding source to favourites button to use ajax to avoid page reload [#614](https://github.com/askap-vast/vast-pipeline/pull/614).
@@ -54,6 +57,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 #### Fixed
 
+- Fixed docs issue that stopped serializers and views being shown in the code reference [#627](https://github.com/askap-vast/vast-pipeline/pull/627).
 - Fixed broken links to external search results from NED by URI encoding source names [#633](https://github.com/askap-vast/vast-pipeline/pull/633).
 - Fixed a regression from pandas==1.4.0 that caused empty groups to be passed to an apply function [#632](https://github.com/askap-vast/vast-pipeline/pull/632).
 - Fixed source names to be IAU compliant [#618](https://github.com/askap-vast/vast-pipeline/pull/618).
@@ -80,6 +84,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 #### List of PRs
 
+- [#627](https://github.com/askap-vast/vast-pipeline/pull/627): dep, docs: Documentation update and versioning.
 - [#633](https://github.com/askap-vast/vast-pipeline/pull/633): fix: URI encode NED object names.
 - [#632](https://github.com/askap-vast/vast-pipeline/pull/632): fix: skip empty groups in new sources groupby-apply.
 - [#634](https://github.com/askap-vast/vast-pipeline/pull/634): dep: bump Jinja2 to v3.

diff --git a/docs/architecture/intro.md b/docs/architecture/intro.md
@@ -35,7 +35,6 @@ The front-end is built in simple HTML, CSS and Javascript using a freely availab
 * [Pyarrow 0.17+](https://arrow.apache.org/docs/python/install.html){:target="_blank"}
 * [Postgres 10+](https://www.postgresql.org/){:target="_blank"}
   * [Q3C](https://github.com/segasai/q3c){:target="_blank"}
-* [Vaex 3+](https://vaex.readthedocs.io/en/latest/){:target="_blank"}
 
 ### Front-End
 

diff --git a/docs/developing/docsdev.md b/docs/developing/docsdev.md
@@ -211,6 +211,14 @@ For example, using the `vast_pipeline` as the base for the python files and `ref
 
 Please refer to the [`mkdocstrings` documentation ](https://mkdocstrings.github.io){:target="_blank"} for full details of the options available to declare in `mkdocs.yml`.
 
+## Versioning
+
+Versioning is enabled on the documentation by using the [`mike`](https://github.com/jimporter/mike){:target="_blank"} package.
+The documentation is published for each release version, along with a development version that is updated with every commit to the default `dev` branch.
+Setup of this has been completed on the initial deployment, and the GitHub workflows will automatically take care of the continual deployment.
+Vist the `mike` package page linked above for details on general management commands such as how to delete a version.
+
 ## Deployment to GitHub pages
 
-Automatic deployment to GitHub pages is set up using GitHub actions and workflows. See source code under the `.github` folder.
+Automatic deployment to GitHub pages is set up using GitHub actions and workflows. 
+See the workflows `ci-docs-dev.yml` and `ci-docs-release.yml`.
diff --git a/docs/gen_doc_stubs.py b/docs/gen_doc_stubs.py
@@ -11,7 +11,7 @@
 # See https://github.com/mkdocstrings/mkdocstrings/issues/141
 # __init__ is there just to avoid building these.
 # TODO: Fix Django pages for mkdocs.
-problem_files = ['serializers.py', 'views.py', '__init__.py', '_version.py']
+problem_files = ['__init__.py', '_version.py']
 
 for path in Path("vast_pipeline").glob("**/*.py"):
 

diff --git a/docs/theme/main.html b/docs/theme/main.html
@@ -28,13 +28,17 @@
 {% block announce %}
   <!-- Extra stylesing -->
   <style>
-      .md-announce a,
-      .md-announce a:focus,
-      .md-announce a:hover{color:currentColor}.md-announce
-      strong{white-space:nowrap}.md-announce}
+      .md-banner a,
+      .md-banner a:focus,
+      .md-banner a:hover{color:currentColor}.md-banner
+      strong{white-space:nowrap}.md-banner}
   </style>
 
-  <a href="{{ base_url }}/changelog/"><strong>New in version 1.0.0</strong>: Documentation, add epoch mode and more 🙌. Check the <strong>release notes!</strong></a>
+  <a href="{{ base_url }}/changelog/">
+    <strong>
+     Development Version 🧑‍💻: </strong> Check the <strong>release notes
+    </strong> for the latest changes!
+  </a>
 
 {% endblock %}
 
@@ -48,3 +52,10 @@
     <script src="{{ base_url }}/js/lightgallery.min.js"></script>
     <script src="{{ base_url }}/js/lg-zoom.js"></script>
 {% endblock libs %}
+
+{% block outdated %}
+  You're viewing an outdated or development version.
+  <a href="{{ '../' ~ base_url }}">
+    <strong>Click here to go to latest stable release.</strong>
+  </a>
+{% endblock %}
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -55,7 +55,8 @@ markdown_extensions:
   - pymdownx.caret
   - pymdownx.details
   - pymdownx.inlinehilite
-  - pymdownx.tabbed
+  - pymdownx.tabbed:
+      alternate_style: true
   - pymdownx.superfences
   - pymdownx.highlight
   - pymdownx.tabbed
@@ -170,16 +171,18 @@ nav:
         - forms.py: reference/forms.md
         - models.py: reference/models.md
         - plots.py: reference/plots.md
-        # - serializers.py: reference/serializers.md
+        - serializers.py: reference/serializers.md
         - signals.py: reference/signals.md
         - urls.py: reference/urls.md
-        # - views.py: reference/views.md
+        - views.py: reference/views.md
 
 plugins:
   - search
   - git-revision-date-localized:
       fallback_to_build_date: true
       enable_creation_date: true
+      exclude:
+        - index.md
   - gen-files:
       scripts:
       # - docs/gen_credits.py
@@ -213,3 +216,5 @@ extra:
       name: vast-pipeline source on GitHub
     - icon: fontawesome/solid/globe
       link: https://vast-survey.org
+  version:
+    provider: mike