Add more breadcrumb and notes

.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "pip" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    insecure-external-code-execution: allow
+    schedule:
+      interval: "daily"
+    labels:
+      - "maintenance"
+      - "dependencies"

.github/workflows/ci-build.yml

@@ -9,7 +9,7 @@ on:
       - main
 
 jobs:
-  stylecheck:
+  precommit:
     runs-on: ubuntu-latest
 
     steps:
@@ -20,10 +20,11 @@ jobs:
         with:
           python-version: 3.9
 
-      - name: Check Style
-        run: |
-          pip install -r requirements_style.txt --disable-pip-version-check
-          make
+      - name: Install pre-commit
+        run: pip install pre-commit
+
+      - name: Run pre-commit
+        run: pre-commit run --all-files || ( git status --short ; git diff ; exit 1 )
 
   build:
     runs-on: ubuntu-latest
@@ -68,11 +69,11 @@ jobs:
           BRANCH: gh-pages
           FOLDER: doc/build/html
           CLEAN: true
-          single-commit: true
+          SINGLE-COMMIT: true
 
   Release:
     if: github.event_name == 'push' && contains(github.ref, 'refs/tags')
-    needs: [stylecheck, build]
+    needs: [precommit, build]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2

.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+repos:
+- repo: https://github.com/psf/black
+  rev: 21.12b0
+  hooks:
+  - id: black
+    exclude: "^({{cookiecutter.project_slug}}/)"
+- repo: https://github.com/asottile/reorder_python_imports
+  rev: v2.6.0
+  hooks:
+  - id: reorder-python-imports
+    args: ["--py37-plus"]
+    exclude: "^({{cookiecutter.project_slug}}/)"
+- repo: https://gitlab.com/PyCQA/flake8
+  rev: 3.9.2
+  hooks:
+  - id: flake8
+    exclude: "^({{cookiecutter.project_slug}}/)"
+- repo: https://github.com/codespell-project/codespell
+  rev: v2.1.0
+  hooks:
+  - id: codespell
+- repo: https://github.com/pycqa/pydocstyle
+  rev: 6.1.1
+  hooks:
+  - id: pydocstyle
+    additional_dependencies: [toml]
+    exclude: "^({{cookiecutter.project_slug}}/)"

LICENSE

@@ -1,6 +1,6 @@
-The MIT License
+MIT License
 
-ANSYS INC. Copyright Copyright (c) 1986-2021
+Copyright (c) 2022 ANSYS, Inc. All rights reserved.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -9,13 +9,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.rst

@@ -43,3 +43,28 @@ documentation.
 
 For usage information, seee `Using this Theme
 <https://sphinxdocs.pyansys.com/usage.html>`_
+
+
+Development and Contributing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Feel free to add features or post issues. To develop this theme::
+
+   git clone https://github.com/pyansys/pyansys-sphinx-theme.git
+   pip install -r requirements_docs.txt
+   make -C doc html
+
+Or for Windows::
+
+   cd doc
+   ./make.bat
+
+We use `pre-commit <https://pre-commit.com/>`_ to simplfy style checks. You can
+optionally use this by following the `installation
+<https://pre-commit.com/#install>`_ and `usage
+<https://pre-commit.com/#usage>`_ guides.
+
+
+License
+~~~~~~~
+This theme is licened under the `MIT License
+<https://raw.githubusercontent.com/pyansys/pyansys-sphinx-theme/main/LICENSE>`_.

doc/source/class_documentation.rst

@@ -9,9 +9,7 @@ There are two main ways of documenting a class using Sphinx.  The
 first approach is to detail its usage via a "User Guide", or manually
 created example designed to be read within documentation. This
 approach works when demonstrating the usage of a class.  For example,
-using the ``.. code:: python`` directive:
-
-.. code::
+using the ``.. code:: python`` directive::
 
    Initialize ``my_module.MyClass`` with initial parameters.  These
    parameters are automatically assigned to the class.

doc/source/conf.py

@@ -1,28 +1,36 @@
 """Sphinx documentation configuration file."""
 from datetime import datetime
 
-from pyansys_sphinx_theme import __version__, pyansys_logo_black
+from pyansys_sphinx_theme import __version__
+from pyansys_sphinx_theme import pyansys_logo_black
 
 # Project information
-project = 'pyansys_sphinx_theme'
+project = "pyansys_sphinx_theme"
 copyright = f"(c) {datetime.now().year} ANSYS, Inc. All rights reserved"
 author = "Ansys Inc."
 release = version = __version__
 
 # use the default pyansys logo
 html_logo = pyansys_logo_black
-html_theme = 'pyansys_sphinx_theme'
+html_theme = "pyansys_sphinx_theme"
 
 # specify the location of your github repo
 html_theme_options = {
     "github_url": "https://github.com/pyansys/pyansys-sphinx-theme",
-    "show_prev_next": False
+    "show_prev_next": False,
+    "show_breadcrumbs": True,
+    "additional_breadcrumbs": [
+        ("PyAnsys", "https://docs.pyansys.com/"),
+    ],
 }
 
+html_short_title = html_title = "PyAnsys Sphinx Theme"
+
+
 # Sphinx extensions
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.autosummary',
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "numpydoc",
     "sphinx.ext.intersphinx",
     "sphinx_copybutton",
@@ -31,9 +39,7 @@
 # Intersphinx mapping
 intersphinx_mapping = {
     "python": ("https://docs.python.org/dev", None),
-
     # kept here as an example
-
     # "scipy": ("https://docs.scipy.org/doc/scipy/reference", None),
     # "numpy": ("https://numpy.org/devdocs", None),
     # "matplotlib": ("https://matplotlib.org/stable", None),
@@ -71,7 +77,7 @@
 templates_path = ["_templates"]
 
 # The suffix(es) of source filenames.
-source_suffix = '.rst'
+source_suffix = ".rst"
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"

doc/source/usage.rst

@@ -64,13 +64,34 @@ breadcrumbs are disabled by default. To add
 breadcrumbs to the pages of your documentation, in the ``conf.py``
 file, add ``"show_breadcrumbs": True`` to the ``html_theme_options`` dictionary.
 
-If you want to add additional 'root' breadcrumbs, such as to the 
-PyAnsys Documentation homepage, add them to the ``html_theme_options`` dictionary as a list of tuples
-with the ``"additional_breadcrumbs"`` key. The tuples are of the form ``("Link text", "url")``.
-
-When on the module homepage, a breadcrumb will be displayed with the homepage title.
-However, this title is not accessible to Sphinx from other documentation pages. Therefore, the ``html_short_title``
-is used as the display text for the documentation homepage breadcrumb. To ensure a consistent user experience
-you should ensure the ``html_short_title`` (or optionally ``html_title`` if ``html_short_title`` is not used)
-is set to the same value as the title of the ``index.rst`` page. If you want to use the version number
-in the ``index.rst`` title, use ``|version|`` to include the package version number. 
+If you want to add additional 'root' breadcrumbs, such as to the PyAnsys
+Documentation homepage, add them to the ``html_theme_options`` dictionary as a
+list of tuples with the ``"additional_breadcrumbs"`` key. The tuples are of the
+form ``("Link text", "url")``.
+
+For example, this theme uses the following ``html_theme_options``:
+
+.. code:: python
+
+   html_theme_options = {
+       "github_url": "https://github.com/pyansys/pyansys-sphinx-theme",
+       "show_prev_next": False,
+       "show_breadcrumbs": True,
+       "additional_breadcrumbs": 
+   }
+
+When on the module homepage, a breadcrumb will be displayed with the homepage
+title.  However, this title is not accessible to Sphinx from other
+documentation pages. Therefore, the ``html_short_title`` is used as the display
+text for the documentation homepage breadcrumb. To ensure a consistent user
+experience you should ensure the ``html_short_title`` (or optionally
+``html_title`` if ``html_short_title`` is not used) is set to the same value as
+the title of the ``index.rst`` page. For example:
+
+.. code:: python
+
+   html_short_title = html_title = 'PyAnsys Sphinx Theme'
+
+If you want to use the version number in
+the ``index.rst`` title, use ``|version|`` to include the package version
+number.

pyansys_sphinx_theme/__init__.py

@@ -1,3 +1,4 @@
+"""This is the pyansys-sphinx-theme module."""
 import os
 
 from ._version import __version__
@@ -7,10 +8,10 @@
 
 # make logo paths available
 pyansys_logo_black = os.path.join(
-    _this_path, 'static', 'pyansys-logo-black-cropped.png'
+    _this_path, "static", "pyansys-logo-black-cropped.png"
 )
 pyansys_logo_white = os.path.join(
-    _this_path, 'static', 'pyansys-logo-white-cropped.png'
+    _this_path, "static", "pyansys-logo-white-cropped.png"
 )
 
 html_logo = pyansys_logo_black
@@ -23,6 +24,7 @@ def get_html_theme_path():
 
 
 def setup(app):
+    """Connect to the sphinx theme app."""
     theme_path = get_html_theme_path()[0]
     app.add_html_theme("pyansys_sphinx_theme", theme_path)
 
@@ -31,7 +33,7 @@ def setup(app):
     app.config.templates_path.append(path_templates)
 
     return {
-        'version': __version__,
-        'parallel_read_safe': True,
-        'parallel_write_safe': True,
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
     }

pyansys_sphinx_theme/_version.py

@@ -6,9 +6,8 @@
 version_info = 0, 0, 'dev0'
 
 """
-
 # major, minor, patch
-version_info = 0, 2, 'dev0'
+version_info = 0, 2, "dev0"
 
 # Nice string for the version
-__version__ = '.'.join(map(str, version_info))
+__version__ = ".".join(map(str, version_info))

pyansys_sphinx_theme/sample_func.py

@@ -1,3 +1,6 @@
+"""Sample functions for pyansys-sphinx-theme."""
+
+
 def func(arg1, arg2):
     """Summary line <should be one one line>.