diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 000000000..483efa176 --- /dev/null +++ b/.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" diff --git a/.github/workflows/ci-build.yml b/.github/workflows/ci-build.yml index 7c5b1a45e..784968527 100644 --- a/.github/workflows/ci-build.yml +++ b/.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 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 000000000..f85fcd6fe --- /dev/null +++ b/.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}}/)" diff --git a/LICENSE b/LICENSE index 68e029fef..ea581cdfa 100644 --- a/LICENSE +++ b/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. diff --git a/Makefile b/Makefile deleted file mode 100644 index 8084de373..000000000 --- a/Makefile +++ /dev/null @@ -1,17 +0,0 @@ -# Simple makefile to simplify repetitive build env management tasks under posix - -CODESPELL_DIRS ?= ./ -CODESPELL_SKIP ?= "*.pyc,*.txt,*.gif,*.png,*.jpg,*.js,*.html,*.doctree,*.ttf,*.woff,*.woff2,*.eot,*.mp4,*.inv,*.pickle,*.ipynb,flycheck*,./.git/*,./.hypothesis/*,*.yml,./doc/build/*,./doc/images/*,./dist/*,*~,.hypothesis*,./doc/source/examples/*,*cover,*.dat,*.mac,\#*,build,PKG-INFO,*.mypy_cache/*" -CODESPELL_IGNORE ?= "ignore_words.txt" - -all: doctest - -doctest: codespell flake8 - -codespell: - @echo "Running codespell" - @codespell $(CODESPELL_DIRS) -S $(CODESPELL_SKIP) -I $(CODESPELL_IGNORE) - -flake8: - @echo "Running flake8" - @flake8 . diff --git a/README.rst b/README.rst index 9a8cce6c1..ead9bc72c 100644 --- a/README.rst +++ b/README.rst @@ -43,3 +43,28 @@ documentation. For usage information, seee `Using this Theme `_ + + +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 `_ to simplfy style checks. You can +optionally use this by following the `installation +`_ and `usage +`_ guides. + + +License +~~~~~~~ +This theme is licened under the `MIT License +`_. diff --git a/doc/source/class_documentation.rst b/doc/source/class_documentation.rst index 3810f8f19..00bbb1c51 100644 --- a/doc/source/class_documentation.rst +++ b/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. diff --git a/doc/source/conf.py b/doc/source/conf.py index cfed19ab1..f3e33f9ff 100755 --- a/doc/source/conf.py +++ b/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" diff --git a/doc/source/usage.rst b/doc/source/usage.rst index 45c78fe3b..0c3f132dd 100644 --- a/doc/source/usage.rst +++ b/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. diff --git a/pyansys_sphinx_theme/__init__.py b/pyansys_sphinx_theme/__init__.py index e71306aab..b738af0e9 100644 --- a/pyansys_sphinx_theme/__init__.py +++ b/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, } diff --git a/pyansys_sphinx_theme/_version.py b/pyansys_sphinx_theme/_version.py index b4c1419cb..dee1db535 100644 --- a/pyansys_sphinx_theme/_version.py +++ b/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)) diff --git a/pyansys_sphinx_theme/sample_func.py b/pyansys_sphinx_theme/sample_func.py index f9b0f0771..de564a2c6 100644 --- a/pyansys_sphinx_theme/sample_func.py +++ b/pyansys_sphinx_theme/sample_func.py @@ -1,3 +1,6 @@ +"""Sample functions for pyansys-sphinx-theme.""" + + def func(arg1, arg2): """Summary line . diff --git a/pyansys_sphinx_theme/samples.py b/pyansys_sphinx_theme/samples.py index 4bee8e7ea..7ed428a1e 100644 --- a/pyansys_sphinx_theme/samples.py +++ b/pyansys_sphinx_theme/samples.py @@ -1,3 +1,4 @@ +"""Sample classes and functions for pyansys-sphinx-theme.""" from math import sqrt @@ -30,6 +31,7 @@ class ExampleClass: """ def __init__(self, param1, param2, param3=0): + """Initialize the ExampleClass.""" self.attr1 = param1 self.attr2 = param2 self.attr3 = param3 @@ -51,11 +53,13 @@ def readonly_property(self) -> str: @property def readwrite_property(self): - """Properties with both a getter and setter - should only be documented in their getter method. + """Set or return the readwrite property. - If the setter method contains notable behavior, it should be - mentioned here. + Properties with both a getter and setter should only be documented in + their getter method. + + If the setter method contains notable behavior, it should be mentioned + here. Examples -------- @@ -87,11 +91,11 @@ def example_method(self, param1, param2): Returns ------- bool - True if successful, False otherwise. + ``True`` if successful, ``False`` otherwise. Notes ----- - Do not include the `self` parameter in the ``Parameters`` section. + Do not include the ``self`` parameter in the ``Parameters`` section. Examples -------- @@ -117,7 +121,7 @@ def __special__(self): """ pass - def __special_without_docstring__(self): + def __special_without_docstring__(self): # noqa: D105 pass def _private(self): @@ -159,6 +163,7 @@ class Complex(object): """ def __init__(self, real, imag=0.0): + """Initialize the complex number.""" self._real = float(real) self._imag = float(imag) @@ -203,33 +208,41 @@ def imag(self, imag): self._imag = float(imag) def __add__(self, other): + """Add two complex numbers.""" return Complex(self._real + other.real, self._imag + other.imag) def __sub__(self, other): + """Subtract two complex numbers.""" return Complex(self._real - other.real, self._imag - other.imag) def __mul__(self, other): - return Complex((self._real * other.real) - (self._imag * other.imag), - (self._imag * other.real) + (self._real * other.imag)) + """Multiply two complex numbers.""" + return Complex( + (self._real * other.real) - (self._imag * other.imag), + (self._imag * other.real) + (self._real * other.imag), + ) def __truediv__(self, other): - r = (other.real**2 + other.imag**2) - return Complex((self._real*other.real - self._imag*other.imag)/r, - (self._imag*other.real + self._real*other.imag)/r) + """Divide two complex numbers.""" + r = other.real ** 2 + other.imag ** 2 + return Complex( + (self._real * other.real - self._imag * other.imag) / r, + (self._imag * other.real + self._real * other.imag) / r, + ) @property def abs(self): - """Absolute value of this number + """Return the absolute value of this number. Examples -------- >>> my_num = Complex(real=1, imag=1.0) >>> my_num.abs """ - new = self._real**2 + self._imag**2 + new = self._real ** 2 + self._imag ** 2 return Complex(sqrt(new.real)) - def __repr__(self): + def __repr__(self): # noqa: D105 if self._imag < 0: - return f'({self._real} - {abs(self._imag)}j)' - return f'({self._real} + {self._imag}j)' + return f"({self._real} - {abs(self._imag)}j)" + return f"({self._real} + {self._imag}j)" diff --git a/pyansys_sphinx_theme/static/css/theme.css b/pyansys_sphinx_theme/static/css/theme.css index 6e3c9c238..9eefef1b9 100644 --- a/pyansys_sphinx_theme/static/css/theme.css +++ b/pyansys_sphinx_theme/static/css/theme.css @@ -146,7 +146,15 @@ color: #C89211; font-family: 'Inconsolata'; font-weight: bold; - font-size: 15.5px; + font-size: 107%; +} + +.xref.std.std-ref { + color: #C89211; + font-family: 'Inconsolata'; + font-weight: bold; + font-style: italic; + font-size: 107%; } .sig-prename { diff --git a/requirements_docs.txt b/requirements_docs.txt index 55f6d5a8a..a81151740 100644 --- a/requirements_docs.txt +++ b/requirements_docs.txt @@ -1,4 +1,3 @@ -Sphinx -https://github.com/numpy/numpydoc/archive/main.zip # need latest -pyansys_sphinx_theme -sphinx-copybutton +Sphinx==4.4.0 +numpydoc==1.2 +sphinx-copybutton==0.5.0 diff --git a/requirements_style.txt b/requirements_style.txt deleted file mode 100755 index 1cab1c4f9..000000000 --- a/requirements_style.txt +++ /dev/null @@ -1,2 +0,0 @@ -codespell==2.0.0 -flake8==3.9.2 diff --git a/setup.py b/setup.py index 52ea171ec..197da8143 100644 --- a/setup.py +++ b/setup.py @@ -10,13 +10,14 @@ HERE = os.path.abspath(os.path.dirname(__file__)) __version__ = None -version_file = os.path.join(HERE, 'pyansys_sphinx_theme', '_version.py') -with io_open(version_file, mode='r') as fd: +version_file = os.path.join(HERE, "pyansys_sphinx_theme", "_version.py") +with io_open(version_file, mode="r") as fd: exec(fd.read()) def read(rel_path): - with codecs.open(os.path.join(HERE, rel_path), 'r') as fp: + """Read a raw file.""" + with codecs.open(os.path.join(HERE, rel_path), "r") as fp: return fp.read() @@ -39,7 +40,9 @@ def read(rel_path): packages=["pyansys_sphinx_theme"], include_package_data=True, # See http://www.sphinx-doc.org/en/stable/theming.html#distribute-your-theme-as-a-python-package - entry_points={"sphinx.html_themes": ["pyansys_sphinx_theme = pyansys_sphinx_theme"]}, + entry_points={ + "sphinx.html_themes": ["pyansys_sphinx_theme = pyansys_sphinx_theme"] + }, install_requires=["sphinx>=4.0.0", "pydata-sphinx-theme==0.7.2"], python_requires=">=3.5", classifiers=[