Merge pull request #22 from djpugh/feature/material-docs

Updating Documentation Theme

.github/pr-labeler.yaml

@@ -1,4 +1,4 @@
 feature: ['feature/*', 'feat/*']
 fix: fix/*
-chore: chore/*
+chore: ['chore/*', 'renovate/*']
 fixed-branch: fixed-branch-name

.github/workflows/pipeline.yml

@@ -3,6 +3,10 @@ name: Pipeline
 
 on:
   push:
+    branches-ignore:
+      - gh-pages
+    tags-ignore:
+      - docs-*
   pull_request:
   release:
     types: [published]
@@ -85,7 +89,7 @@ jobs:
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
 
   license-scan:
-    if: github.event_name == 'pull_request' && contains(github.base_ref, 'master') || (github.event_name == 'push' && startsWith(github.ref, 'refs/tags')) || github.event_name == 'release'
+    if: github.event_name == 'pull_request' && contains(github.base_ref, 'main') || (github.event_name == 'push' && startsWith(github.ref, 'refs/tags')) || github.event_name == 'release'
 
     name: Scan Licenses
     runs-on: ubuntu-latest
@@ -117,7 +121,7 @@ jobs:
       uses: github/codeql-action/analyze@v1
 
   collate-packages:
-    if: github.event_name == 'pull_request' && contains(github.base_ref, 'master') || (github.event_name == 'push' && startsWith(github.ref, 'refs/tags')) || github.event_name == 'release'
+    if: github.event_name == 'pull_request' && contains(github.base_ref, 'main') || (github.event_name == 'push' && startsWith(github.ref, 'refs/tags')) || github.event_name == 'release'
     name: Collate Wheels - ${{ matrix.os }}
     runs-on: ${{ matrix.os }}-latest
     strategy:
@@ -151,7 +155,7 @@ jobs:
           ./wheels/*
 
   build:
-    if: github.event_name == 'pull_request' && contains(github.base_ref, 'master') || (github.event_name == 'push' && startsWith(github.ref, 'refs/tags')) || github.event_name == 'release'
+    if: github.event_name == 'pull_request' && contains(github.base_ref, 'main') || (github.event_name == 'push' && startsWith(github.ref, 'refs/tags')) || github.event_name == 'release'
     name: Build Package
     runs-on: ${{ matrix.os }}-latest
     needs:
@@ -192,7 +196,7 @@ jobs:
             dist/*
 
   docs:
-    if: github.event_name == 'pull_request' && contains(github.base_ref, 'master') || (github.event_name == 'push' && startsWith(github.ref, 'refs/tags')) || github.event_name == 'release'
+    if: github.event_name == 'pull_request' && contains(github.base_ref, 'main') || (github.event_name == 'push' && startsWith(github.ref, 'refs/tags')) || github.event_name == 'release'
     name: Build docs
     needs:
       - collate-packages
@@ -227,7 +231,7 @@ jobs:
             docs/html/*
 
   test-build:
-    if: github.event_name == 'pull_request' && contains(github.base_ref, 'master') || (github.event_name == 'push' && startsWith(github.ref, 'refs/tags')) || github.event_name == 'release'
+    if: github.event_name == 'pull_request' && contains(github.base_ref, 'main') || (github.event_name == 'push' && startsWith(github.ref, 'refs/tags')) || github.event_name == 'release'
     name: Test Build Python ${{ matrix.py }} - ${{ matrix.os }}
     needs:
       - build
@@ -324,7 +328,7 @@ jobs:
         if: startsWith(github.ref, 'refs/tags')
 
   publish-docs:
-    if: (github.event_name == 'push' && startsWith(github.ref, 'refs/tags')) || github.event_name == 'release'
+    if: (github.event_name == 'push' && startsWith(github.ref, 'refs/tags')  && !(contains(github.ref, 'gh-pages') || contains(github.ref, 'docs')) ) || github.event_name == 'release'
     name: Publish Docs
     runs-on: ubuntu-latest
     needs: 
@@ -336,9 +340,15 @@ jobs:
         with:
           name: docs
           path: ./docs/html
-
+      - name: Get Version
+        id: get_version
+        run: |
+          tag_name=$(echo ${{github.ref}} | cut -d/ -f3)
+          echo "::set-output name=tag_name::$tag_name"
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs/html
+          publish_dir: ./docs/html
+          tag_name: docs-${{ steps.get_version.outputs.tag_name }}
+          tag_message: 'Docs ${{ steps.get_version.outputs.tag_name }}'

.github/workflows/release-management.yaml

@@ -5,7 +5,7 @@ on:
   push:
     # branches to consider in the event; optional, defaults to all
     branches:
-      - master
+      - main
 
 jobs:
   update_draft_release:

docs/source/conf.py

@@ -18,6 +18,7 @@
 import subprocess
 
 from pkg_resources import parse_requirements
+import sphinx_material
 
 from azure_devops_artifacts_helpers import __version__
 __author__ = 'David Pugh'
@@ -44,11 +45,12 @@
     'sphinx.ext.todo',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
-    'sphinx_github_changelog'
+    'sphinx_github_changelog',
+    'sphinx_material'
 ]
 
 with open(str(Path(__file__).parents[2]/'embed_requirements.txt')) as f:
-  artifacts_keyring_version = [u for u in parse_requirements(f.read()) if 'artifacts' in u.name and 'keyring' in u.name][0]
+  artifacts_keyring_version = [f'``{u}``' for u in parse_requirements(f.read()) if 'artifacts' in u.name and 'keyring' in u.name][0]
 
 # virtualenv_cli = subprocess.check_call(['virtualenv', '--help'])
 
@@ -119,7 +121,7 @@
 #show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+# pygments_style = 'sphinx'
 
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
@@ -132,12 +134,66 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
-
-if not on_rtd:  # only import and set the theme if we're building docs locally
-    import sphinx_rtd_theme
-    html_theme = 'sphinx_rtd_theme'
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+# on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+# if not on_rtd:  # only import and set the theme if we're building docs locally
+#     import sphinx_rtd_theme
+#     html_theme = 'sphinx_rtd_theme'
+#     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_theme = 'sphinx_material'
+
+# Set link name generated in the top bar.
+html_title = 'Azure DevOps Artifacts Helpers'
+
+html_theme_path = sphinx_material.html_theme_path()
+html_context = sphinx_material.get_html_context()
+html_theme_options = {
+
+    # Set the name of the project to appear in the navigation.
+    'nav_title': html_title,
+
+    # Specify a base_url used to generate sitemap.xml. If not
+    # specified, then no sitemap will be built.
+    'base_url': 'https://djpugh.github.io/azure_devops_artifacts_helpers',
+
+    # Set the repo location to get a badge with stats
+    'repo_url': 'https://github.com/djpugh/azure_devops_artifacts_helpers/',
+    'repo_name': 'azure_devops_artifacts_helpers',
+
+    # Visible levels of the global TOC; -1 means unlimited
+    'globaltoc_depth': -1,
+    # If False, expand all TOC entries
+    'globaltoc_collapse': False,
+    # If True, show hidden TOC entries
+    'globaltoc_includehidden': False,
+    "logo_icon": "cloud_circle",
+    "repo_type": "github",
+    "globaltoc_depth": 2,
+    "color_primary": "pink",
+    "color_accent": "indigo",
+    "touch_icon": "images/apple-icon-152x152.png",
+    "theme_color": "#2196f3",
+    "master_doc": False,
+    "nav_links": [
+        {
+            "href": "https://virtualenv.pypa.io/en/stable/",
+            "internal": False,
+            "title": "Virtualenv",
+        },
+        {
+            "href": "https://azure.microsoft.com/en-gb/services/devops/",
+            "internal": False,
+            "title": "Azure DevOps",
+        }
+    ],
+    "heroes": {
+        "index": "Adding Azure Active Directory Authentical for fastAPI",
+    },
+    "version_dropdown": False,
+}
+html_sidebars = {
+    "**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]
+}
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.

docs/source/index.rst

@@ -48,15 +48,19 @@ The repository is open source (MIT Licensed) on |github| `Github <https://github
 .. |github| image:: https://api.iconify.design/logos-github-icon.svg
     :target: https://github.com/djpugh/azure_devops_artifacts_helpers
 
+.. toctree::
+    :caption: Basic Use
+    :maxdepth: 1
+
+    Installation <installation>
+    Usage <usage>
 
 .. toctree::
-   :maxdepth: 1
-
-   Release Information <changelog>
-   Installation <installation>
-   Usage <usage>
-   Development <development>
+    :caption: Changes and Contributing
+    :maxdepth: 1
 
+    Release Information <changelog>
+    Contributing <development>
 
 ---------------------------------------
 

docs/source/usage.rst

@@ -5,6 +5,10 @@ Using azure_devops_artifacts_helpers
 :pypi:`azure_devops_artifacts_helpers` is an extension to :pypi:`virtualenv`. Once installed, you should see ``azdo-pip`` 
 in the ``--seeders`` options when running ``virtualenv --help``.
 
+To create a virtualenv with |artifacts_keyring_version| installed use::
+
+    $ virtualenv <venv-name> --seeders=azdo-pip
+
 There is also a tox plugin that can be included using the ``tox`` ``requires`` argument in ``tox.ini``
 
 .. code-block:: ini

tox.ini

@@ -13,9 +13,9 @@ deps =
     test,develop: pytest
     test,develop: pytest-cov
     test,develop: tox
-    docs: sphinx
-    docs: sphinx_rtd_theme
-    docs: sphinx_github_changelog
+    docs,develop: sphinx
+    docs,develop: sphinx_material
+    docs,develop: sphinx_github_changelog
     build: wheel
     populate: click