diff --git a/.gitignore b/.gitignore index a37be99b..2593ec75 100644 --- a/.gitignore +++ b/.gitignore @@ -8,7 +8,6 @@ __pycache__/ # Distribution / packaging .Python env/ -.venv build/ develop-eggs/ dist/ diff --git a/template/README.md.jinja b/template/README.md.jinja new file mode 100644 index 00000000..586f6ee8 --- /dev/null +++ b/template/README.md.jinja @@ -0,0 +1,35 @@ +[![CI]({{repo_url}}/actions/workflows/ci.yml/badge.svg)]({{repo_url}}/actions/workflows/ci.yml) +[![Coverage](https://codecov.io/gh/{{github_org}}/{{repo_name}}/branch/master/graph/badge.svg)](https://codecov.io/gh/{{github_org}}/{{repo_name}}) +[![PyPI](https://img.shields.io/pypi/v/{{pypi_name}}.svg)](https://pypi.org/project/{{pypi_name}}) +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) + +# {{ package_name }} + +This is where you should write a short paragraph that describes what your module does, +how it does it, and why people should use it. + +Source | <{{repo_url}}> +:---: | :---: +PyPI | `pip install {{pypi_name}}` +Documentation | <{{docs_url}}> +Releases | <{{repo_url}}/releases> + +This is where you should put some images or code snippets that illustrate +some relevant examples. If it is a library then you might put some +introductory code here: + +```python +from {{package_name}} import __version__ + +print(f"Hello {{package_name}} {__version__}") +``` + +Or if it is a commandline tool then you might put some example commands here: + +``` +python -m {{package_name}} --version +``` + + + +See {{docs_url}} for more detailed documentation. diff --git a/template/README.rst.jinja b/template/README.rst.jinja deleted file mode 100644 index 91c56595..00000000 --- a/template/README.rst.jinja +++ /dev/null @@ -1,56 +0,0 @@ -{{package_name}} -============================================================================= - -|code_ci| |docs_ci| |coverage| |pypi_version| |license| - -This is where you should write a short paragraph that describes what your module does, -how it does it, and why people should use it. - -============== ============================================================== -PyPI ``pip install {{distribution_name}}`` -Source code {{repo_url}} -{% if docs_type=="sphinx" %}Documentation {{docs_url}}{% endif %} -Releases {{repo_url}}/releases -============== ============================================================== - -This is where you should put some images or code snippets that illustrate -some relevant examples. If it is a library then you might put some -introductory code here: - -.. code-block:: python - - from {{package_name}} import __version__ - - print(f"Hello {{package_name}} {__version__}") - -Or if it is a commandline tool then you might put some example commands here:: - - $ python -m {{package_name}} --version - -.. |code_ci| image:: {{repo_url}}/actions/workflows/code.yml/badge.svg?branch=main - :target: {{repo_url}}/actions/workflows/code.yml - :alt: Code CI - -.. |docs_ci| image:: {{repo_url}}/actions/workflows/docs.yml/badge.svg?branch=main - :target: {{repo_url}}/actions/workflows/docs.yml - :alt: Docs CI - -.. |coverage| image:: https://codecov.io/gh/{{github_org}}/{{repo_name}}/branch/main/graph/badge.svg - :target: https://codecov.io/gh/{{github_org}}/{{repo_name}} - :alt: Test Coverage - -.. |pypi_version| image:: https://img.shields.io/pypi/v/{{distribution_name}}.svg - :target: https://pypi.org/project/{{distribution_name}} - :alt: Latest PyPI version - -.. |license| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg - :target: https://opensource.org/licenses/Apache-2.0 - :alt: Apache License - -{% if docs_type=="sphinx" %} -.. - Anything below this line is used when viewing README.rst and will be replaced - when included in index.rst - -See {{docs_url}} for more detailed documentation. -{% endif %} \ No newline at end of file diff --git a/template/pyproject.toml.jinja b/template/pyproject.toml.jinja index 022da055..86f7bb8d 100644 --- a/template/pyproject.toml.jinja +++ b/template/pyproject.toml.jinja @@ -25,10 +25,12 @@ requires-python = ">=3.7" [project.optional-dependencies] dev = [ "black", - "pyright", + "copier", + "myst-parser", "pipdeptree", "pre-commit", "pydata-sphinx-theme>=0.12", + "pyright", "pytest", "pytest-cov", "ruff", @@ -37,7 +39,6 @@ dev = [ "sphinx-design", "tox-direct", "types-mock", - "copier", ] [project.scripts] diff --git "a/template/{% if git_platform==\"github.com\" %}.github{% endif %}/CONTRIBUTING.md.jinja" "b/template/{% if git_platform==\"github.com\" %}.github{% endif %}/CONTRIBUTING.md.jinja" new file mode 100644 index 00000000..408d7b8d --- /dev/null +++ "b/template/{% if git_platform==\"github.com\" %}.github{% endif %}/CONTRIBUTING.md.jinja" @@ -0,0 +1,27 @@ +# Contribute to the project + +Contributions and issues are most welcome! All issues and pull requests are +handled through [GitHub]({{ repo_url }}/issues). Also, please check for any existing issues before +filing a new one. If you have a great idea but it involves big changes, please +file a ticket before making a pull request! We want to make sure you don't spend +your time coding something that might not fit the scope of the project. + +## Issue or Discussion? + +Github also offers [discussions]({{ repo_url }}/discussions) as a place to ask questions and share ideas. If +your issue is open ended and it is not obvious when it can be "closed", please +raise it as a discussion instead. + +## Code Coverage + +While 100% code coverage does not make a library bug-free, it significantly +reduces the number of easily caught bugs! Please make sure coverage remains the +same or is improved by a pull request! + +## Developer Information + +It is recommended that developers use a [vscode devcontainer](https://code.visualstudio.com/docs/devcontainers/containers). This repository contains configuration to set up a containerized development environment that suits its own needs. + +This project was created using the [Diamond Light Source Copier Template](https://github.com/DiamondLightSource/python-copier-template) for Python projects. +The template's [Developer Guide](https://diamondlightsource.github.io/python-copier-template) contains detailed information on setting up a development environment, running the tests and what standards the code and documentation +should follow. diff --git "a/template/{% if git_platform==\"github.com\" %}.github{% endif %}/CONTRIBUTING.rst.jinja" "b/template/{% if git_platform==\"github.com\" %}.github{% endif %}/CONTRIBUTING.rst.jinja" deleted file mode 100644 index cfe4bdd5..00000000 --- "a/template/{% if git_platform==\"github.com\" %}.github{% endif %}/CONTRIBUTING.rst.jinja" +++ /dev/null @@ -1,35 +0,0 @@ -Contributing to the project -=========================== - -Contributions and issues are most welcome! All issues and pull requests are -handled through GitHub_. Also, please check for any existing issues before -filing a new one. If you have a great idea but it involves big changes, please -file a ticket before making a pull request! We want to make sure you don't spend -your time coding something that might not fit the scope of the project. - -.. _GitHub: {{ repo_url }}/issues - -Issue or Discussion? --------------------- - -Github also offers discussions_ as a place to ask questions and share ideas. If -your issue is open ended and it is not obvious when it can be "closed", please -raise it as a discussion instead. - -.. _discussions: {{ repo_url }}/discussions - -Code coverage -------------- - -While 100% code coverage does not make a library bug-free, it significantly -reduces the number of easily caught bugs! Please make sure coverage remains the -same or is improved by a pull request! - -Developer guide ---------------- - -The `Developer Guide`_ contains information on setting up a development -environment, running the tests and what standards the code and documentation -should follow. - -.. _Developer Guide: {{ docs_url }}/main/developer/how-to/contribute.html diff --git a/template/{% if sphinx %}docs{% endif %}/conf.py.jinja b/template/{% if sphinx %}docs{% endif %}/conf.py.jinja index d5ed444e..1909f762 100644 --- a/template/{% if sphinx %}docs{% endif %}/conf.py.jinja +++ b/template/{% if sphinx %}docs{% endif %}/conf.py.jinja @@ -44,8 +44,13 @@ extensions = [ "sphinx_copybutton", # For the card element "sphinx_design", + # So we can write markdown files + "myst_parser", ] +# So we can use the ::: syntax +myst_enable_extensions = ["colon_fence"] + # If true, Sphinx will warn about all references where the target cannot # be found. nitpicky = True @@ -82,9 +87,6 @@ graphviz_output_format = "svg" # role, that is, for text marked up `like this` default_role = "any" -# The suffix of source filenames. -source_suffix = ".rst" - # The master toctree document. master_doc = "index" diff --git a/template/{% if sphinx %}docs{% endif %}/developer/explanations/decisions.rst b/template/{% if sphinx %}docs{% endif %}/developer/explanations/decisions.rst deleted file mode 100644 index 5841e6ea..00000000 --- a/template/{% if sphinx %}docs{% endif %}/developer/explanations/decisions.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. This Source Code Form is subject to the terms of the Mozilla Public -.. License, v. 2.0. If a copy of the MPL was not distributed with this -.. file, You can obtain one at http://mozilla.org/MPL/2.0/. - -Architectural Decision Records -============================== - -We record major architectural decisions in Architecture Decision Records (ADRs), -as `described by Michael Nygard -`_. -Below is the list of our current ADRs. - -.. toctree:: - :maxdepth: 1 - :glob: - - decisions/* \ No newline at end of file diff --git a/template/{% if sphinx %}docs{% endif %}/developer/explanations/decisions/0001-record-architecture-decisions.rst b/template/{% if sphinx %}docs{% endif %}/developer/explanations/decisions/0001-record-architecture-decisions.rst deleted file mode 100644 index 0604062c..00000000 --- a/template/{% if sphinx %}docs{% endif %}/developer/explanations/decisions/0001-record-architecture-decisions.rst +++ /dev/null @@ -1,24 +0,0 @@ -1. Record architecture decisions -================================ - -Status ------- - -Accepted - -Context -------- - -We need to record the architectural decisions made on this project. - -Decision --------- - -We will use Architecture Decision Records, as `described by Michael Nygard -`_. - -Consequences ------------- - -See Michael Nygard's article, linked above. To create new ADRs we will copy and -paste from existing ones. diff --git a/template/{% if sphinx %}docs{% endif %}/developer/explanations/decisions/0002-switched-to-pip-skeleton.rst.jinja b/template/{% if sphinx %}docs{% endif %}/developer/explanations/decisions/0002-switched-to-pip-skeleton.rst.jinja deleted file mode 100644 index 07d02bd4..00000000 --- a/template/{% if sphinx %}docs{% endif %}/developer/explanations/decisions/0002-switched-to-pip-skeleton.rst.jinja +++ /dev/null @@ -1,33 +0,0 @@ -2. Adopt python_copier_template for project structure -===================================================== - -Status ------- - -Accepted - -Context -------- - -We should use the following `python_copier_template `_. -The template will ensure consistency in developer -environments and package management. - -Decision --------- - -We have switched to using the skeleton. - -Consequences ------------- - -This module will use a fixed set of tools as developed in python_copier_template -and can pull from this template to update the packaging to the latest techniques. - -As such, the developer environment may have changed, the following could be -different: - -- linting -- formatting -- pip venv setup -- CI/CD diff --git a/template/{% if sphinx %}docs{% endif %}/developer/how-to/build-docs.rst b/template/{% if sphinx %}docs{% endif %}/developer/how-to/build-docs.rst deleted file mode 100644 index 11a5e638..00000000 --- a/template/{% if sphinx %}docs{% endif %}/developer/how-to/build-docs.rst +++ /dev/null @@ -1,38 +0,0 @@ -Build the docs using sphinx -=========================== - -You can build the `sphinx`_ based docs from the project directory by running:: - - $ tox -e docs - -This will build the static docs on the ``docs`` directory, which includes API -docs that pull in docstrings from the code. - -.. seealso:: - - `documentation_standards` - -The docs will be built into the ``build/html`` directory, and can be opened -locally with a web browser:: - - $ firefox build/html/index.html - -Autobuild ---------- - -You can also run an autobuild process, which will watch your ``docs`` -directory for changes and rebuild whenever it sees changes, reloading any -browsers watching the pages:: - - $ tox -e docs autobuild - -You can view the pages at localhost:: - - $ firefox http://localhost:8000 - -If you are making changes to source code too, you can tell it to watch -changes in this directory too:: - - $ tox -e docs autobuild -- --watch src - -.. _sphinx: https://www.sphinx-doc.org/ diff --git a/template/{% if sphinx %}docs{% endif %}/developer/how-to/contribute.rst b/template/{% if sphinx %}docs{% endif %}/developer/how-to/contribute.rst deleted file mode 100644 index 65b992f0..00000000 --- a/template/{% if sphinx %}docs{% endif %}/developer/how-to/contribute.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../.github/CONTRIBUTING.rst diff --git a/template/{% if sphinx %}docs{% endif %}/developer/how-to/lint.rst b/template/{% if sphinx %}docs{% endif %}/developer/how-to/lint.rst deleted file mode 100644 index 2df258d8..00000000 --- a/template/{% if sphinx %}docs{% endif %}/developer/how-to/lint.rst +++ /dev/null @@ -1,39 +0,0 @@ -Run linting using pre-commit -============================ - -Code linting is handled by black_ and ruff_ run under pre-commit_. - -Running pre-commit ------------------- - -You can run the above checks on all files with this command:: - - $ tox -e pre-commit - -Or you can install a pre-commit hook that will run each time you do a ``git -commit`` on just the files that have changed:: - - $ pre-commit install - -It is also possible to `automatically enable pre-commit on cloned repositories `_. -This will result in pre-commits being enabled on every repo your user clones from now on. - -Fixing issues -------------- - -If black reports an issue you can tell it to reformat all the files in the -repository:: - - $ black . - -Likewise with ruff:: - - $ ruff --fix . - -Ruff may not be able to automatically fix all issues; in this case, you will have to fix those manually. - -VSCode support --------------- - -The ``.vscode/settings.json`` will run black formatting as well as -ruff checking on save. Issues will be highlighted in the editor window. diff --git a/template/{% if sphinx %}docs{% endif %}/developer/how-to/make-release.rst.jinja b/template/{% if sphinx %}docs{% endif %}/developer/how-to/make-release.rst.jinja deleted file mode 100644 index a12a329e..00000000 --- a/template/{% if sphinx %}docs{% endif %}/developer/how-to/make-release.rst.jinja +++ /dev/null @@ -1,16 +0,0 @@ -Make a release -============== - -To make a new release, please follow this checklist: - -- Choose a new PEP440 compliant release number (see https://peps.python.org/pep-0440/) -- Go to the GitHub release_ page -- Choose ``Draft New Release`` -- Click ``Choose Tag`` and supply the new tag you chose (click create new tag) -- Click ``Generate release notes``, review and edit these notes -- Choose a title and click ``Publish Release`` - -Note that tagging and pushing to the main branch has the same effect except that -you will not get the option to edit the release notes. - -.. _release: {{ repo_url }}/releases diff --git a/template/{% if sphinx %}docs{% endif %}/developer/how-to/pin-requirements.rst b/template/{% if sphinx %}docs{% endif %}/developer/how-to/pin-requirements.rst deleted file mode 100644 index 89639623..00000000 --- a/template/{% if sphinx %}docs{% endif %}/developer/how-to/pin-requirements.rst +++ /dev/null @@ -1,74 +0,0 @@ -Pinning Requirements -==================== - -Introduction ------------- - -By design this project only defines dependencies in one place, i.e. in -the ``requires`` table in ``pyproject.toml``. - -In the ``requires`` table it is possible to pin versions of some dependencies -as needed. For library projects it is best to leave pinning to a minimum so -that your library can be used by the widest range of applications. - -When CI builds the project it will use the latest compatible set of -dependencies available (after applying your pins and any dependencies' pins). - -This approach means that there is a possibility that a future build may -break because an updated release of a dependency has made a breaking change. - -The correct way to fix such an issue is to work out the minimum pinning in -``requires`` that will resolve the problem. However this can be quite hard to -do and may be time consuming when simply trying to release a minor update. - -For this reason we provide a mechanism for locking all dependencies to -the same version as a previous successful release. This is a quick fix that -should guarantee a successful CI build. - -Finding the lock files ----------------------- - -Every release of the project will have a set of requirements files published -as release assets. - -For example take a look at the release page for python3-pip-skeleton-cli here: -https://github.com/DiamondLightSource/python3-pip-skeleton-cli/releases/tag/3.3.0 - -There is a list of requirements*.txt files showing as assets on the release. - -There is one file for each time the CI installed the project into a virtual -environment. There are multiple of these as the CI creates a number of -different environments. - -The files are created using ``pip freeze`` and will contain a full list -of the dependencies and sub-dependencies with pinned versions. - -You can download any of these files by clicking on them. It is best to use -the one that ran with the lowest Python version as this is more likely to -be compatible with all the versions of Python in the test matrix. -i.e. ``requirements-test-ubuntu-latest-3.8.txt`` in this example. - -Applying the lock file ----------------------- - -To apply a lockfile: - -- copy the requirements file you have downloaded to the root of your - repository -- rename it to requirements.txt -- commit it into the repo -- push the changes - -The CI looks for a requirements.txt in the root and will pass it to pip -when installing each of the test environments. pip will then install exactly -the same set of packages as the previous release. - -Removing dependency locking from CI ------------------------------------ - -Once the reasons for locking the build have been resolved it is a good idea -to go back to an unlocked build. This is because you get an early indication -of any incoming problems. - -To restore unlocked builds in CI simply remove requirements.txt from the root -of the repo and push. diff --git a/template/{% if sphinx %}docs{% endif %}/developer/how-to/run-tests.rst b/template/{% if sphinx %}docs{% endif %}/developer/how-to/run-tests.rst deleted file mode 100644 index d2e03644..00000000 --- a/template/{% if sphinx %}docs{% endif %}/developer/how-to/run-tests.rst +++ /dev/null @@ -1,12 +0,0 @@ -Run the tests using pytest -========================== - -Testing is done with pytest_. It will find functions in the project that `look -like tests`_, and run them to check for errors. You can run it with:: - - $ tox -e pytest - -It will also report coverage to the commandline and to ``cov.xml``. - -.. _pytest: https://pytest.org/ -.. _look like tests: https://docs.pytest.org/explanation/goodpractices.html#test-discovery diff --git a/template/{% if sphinx %}docs{% endif %}/developer/how-to/static-analysis.rst b/template/{% if sphinx %}docs{% endif %}/developer/how-to/static-analysis.rst deleted file mode 100644 index dd7eb817..00000000 --- a/template/{% if sphinx %}docs{% endif %}/developer/how-to/static-analysis.rst +++ /dev/null @@ -1,8 +0,0 @@ -Run static analysis using pyright -================================= - -Static type analysis is done with pyright_. It checks type definition in source -files without running them, and highlights potential issues where types do not -match. You can run it with:: - - $ tox -e pyright diff --git a/template/{% if sphinx %}docs{% endif %}/developer/how-to/test-container.rst b/template/{% if sphinx %}docs{% endif %}/developer/how-to/test-container.rst deleted file mode 100644 index a4a43a6f..00000000 --- a/template/{% if sphinx %}docs{% endif %}/developer/how-to/test-container.rst +++ /dev/null @@ -1,25 +0,0 @@ -Container Local Build and Test -============================== - -CI builds a runtime container for the project. The local tests -checks available via ``tox -p`` do not verify this because not -all developers will have docker installed locally. - -If CI is failing to build the container, then it is best to fix and -test the problem locally. This would require that you have docker -or podman installed on your local workstation. - -In the following examples the command ``docker`` is interchangeable with -``podman`` depending on which container cli you have installed. - -To build the container and call it ``test``:: - - cd - docker build -t test . - -To verify that the container runs:: - - docker run -it test --help - -You can pass any other command line parameters to your application -instead of --help. diff --git a/template/{% if sphinx %}docs{% endif %}/developer/how-to/update-tools.rst b/template/{% if sphinx %}docs{% endif %}/developer/how-to/update-tools.rst deleted file mode 100644 index c1075ee8..00000000 --- a/template/{% if sphinx %}docs{% endif %}/developer/how-to/update-tools.rst +++ /dev/null @@ -1,16 +0,0 @@ -Update the tools -================ - -This module is merged with the python3-pip-skeleton_. This is a generic -Python project structure which provides a means to keep tools and -techniques in sync between multiple Python projects. To update to the -latest version of the skeleton, run:: - - $ git pull --rebase=false https://github.com/DiamondLightSource/python3-pip-skeleton - -Any merge conflicts will indicate an area where something has changed that -conflicts with the setup of the current module. Check the `closed pull requests -`_ -of the skeleton module for more details. - -.. _python3-pip-skeleton: https://DiamondLightSource.github.io/python3-pip-skeleton diff --git a/template/{% if sphinx %}docs{% endif %}/developer/index.rst b/template/{% if sphinx %}docs{% endif %}/developer/index.rst deleted file mode 100644 index 8a6369b9..00000000 --- a/template/{% if sphinx %}docs{% endif %}/developer/index.rst +++ /dev/null @@ -1,64 +0,0 @@ -Developer Guide -=============== - -Documentation is split into four categories, also accessible from links in the -side-bar. - -.. grid:: 2 - :gutter: 4 - - .. grid-item-card:: :material-regular:`directions_run;3em` - - .. toctree:: - :caption: Tutorials - :maxdepth: 1 - - tutorials/dev-install - - +++ - - Tutorials for getting up and running as a developer. - - .. grid-item-card:: :material-regular:`task;3em` - - .. toctree:: - :caption: How-to Guides - :maxdepth: 1 - - how-to/contribute - how-to/build-docs - how-to/run-tests - how-to/static-analysis - how-to/lint - how-to/update-tools - how-to/make-release - how-to/pin-requirements - how-to/test-container - - +++ - - Practical step-by-step guides for day-to-day dev tasks. - - .. grid-item-card:: :material-regular:`apartment;3em` - - .. toctree:: - :caption: Explanations - :maxdepth: 1 - - explanations/decisions - - +++ - - Explanations of how and why the architecture is why it is. - - .. grid-item-card:: :material-regular:`description;3em` - - .. toctree:: - :caption: Reference - :maxdepth: 1 - - reference/standards - - +++ - - Technical reference material on standards in use. diff --git a/template/{% if sphinx %}docs{% endif %}/developer/reference/standards.rst b/template/{% if sphinx %}docs{% endif %}/developer/reference/standards.rst deleted file mode 100644 index 1cc9da82..00000000 --- a/template/{% if sphinx %}docs{% endif %}/developer/reference/standards.rst +++ /dev/null @@ -1,63 +0,0 @@ -Standards -========= - -This document defines the code and documentation standards used in this -repository. - -Code Standards --------------- - -The code in this repository conforms to standards set by the following tools: - -- black_ for code formatting -- ruff_ for style checks -- pyright_ for static type checking - -.. seealso:: - - How-to guides `../how-to/lint` and `../how-to/static-analysis` - -.. _documentation_standards: - -Documentation Standards ------------------------ - -Docstrings are pre-processed using the Sphinx Napoleon extension. As such, -google-style_ is considered as standard for this repository. Please use type -hints in the function signature for types. For example: - -.. code:: python - - def func(arg1: str, arg2: int) -> bool: - """Summary line. - - Extended description of function. - - Args: - arg1: Description of arg1 - arg2: Description of arg2 - - Returns: - Description of return value - """ - return True - -.. _google-style: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/index.html#google-vs-numpy - -Documentation is contained in the ``docs`` directory and extracted from -docstrings of the API. - -Docs follow the underlining convention:: - - Headling 1 (page title) - ======================= - - Heading 2 - --------- - - Heading 3 - ~~~~~~~~~ - -.. seealso:: - - How-to guide `../how-to/build-docs` diff --git a/template/{% if sphinx %}docs{% endif %}/developer/tutorials/dev-install.rst.jinja b/template/{% if sphinx %}docs{% endif %}/developer/tutorials/dev-install.rst.jinja deleted file mode 100644 index 1510931d..00000000 --- a/template/{% if sphinx %}docs{% endif %}/developer/tutorials/dev-install.rst.jinja +++ /dev/null @@ -1,68 +0,0 @@ -Developer install -================= - -These instructions will take you through the minimal steps required to get a dev -environment setup, so you can run the tests locally. - -Clone the repository --------------------- - -First clone the repository locally using `Git -`_:: - - $ git clone git://github.com/{{ github_org }}/{{ repo_name }}.git - -Install dependencies --------------------- - -You can choose to either develop on the host machine using a `venv` (which -requires python 3.8 or later) or to run in a container under `VSCode -`_ - -.. tab-set:: - - .. tab-item:: Local virtualenv - - .. code:: - - $ cd {{ repo_name }} - $ python3 -m venv venv - $ source venv/bin/activate - $ pip install -e '.[dev]' - - .. tab-item:: VSCode devcontainer - - .. code:: - - $ code {{ repo_name }} - # Click on 'Reopen in Container' when prompted - # Open a new terminal - - .. note:: - - See the epics-containers_ documentation for more complex - use cases, such as integration with podman. - -See what was installed ----------------------- - -To see a graph of the python package dependency tree type:: - - $ pipdeptree - -Build and test --------------- - -Now you have a development environment you can run the tests in a terminal:: - - $ tox -p - -This will run in parallel the following checks: - -- `../how-to/build-docs` -- `../how-to/run-tests` -- `../how-to/static-analysis` -- `../how-to/lint` - - -.. _epics-containers: https://epics-containers.github.io/main/user/tutorials/devcontainer.html diff --git a/template/{% if sphinx %}docs{% endif %}/explanations.md b/template/{% if sphinx %}docs{% endif %}/explanations.md new file mode 100644 index 00000000..73ab289b --- /dev/null +++ b/template/{% if sphinx %}docs{% endif %}/explanations.md @@ -0,0 +1,10 @@ +# Explanations + +Explanations of how it works and why it works that way. + +```{toctree} +:maxdepth: 1 +:glob: + +explanations/* +``` diff --git a/template/{% if sphinx %}docs{% endif %}/explanations/decisions.md b/template/{% if sphinx %}docs{% endif %}/explanations/decisions.md new file mode 100644 index 00000000..f97c2f9f --- /dev/null +++ b/template/{% if sphinx %}docs{% endif %}/explanations/decisions.md @@ -0,0 +1,18 @@ +% This Source Code Form is subject to the terms of the Mozilla Public + +% License, v. 2.0. If a copy of the MPL was not distributed with this + +% file, You can obtain one at http://mozilla.org/MPL/2.0/. + +# Architectural Decision Records + +We record major architectural decisions in Architecture Decision Records (ADRs), +as [described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). +Below is the list of our current ADRs. + +```{toctree} +:glob: true +:maxdepth: 1 + +decisions/* +``` diff --git a/template/{% if sphinx %}docs{% endif %}/explanations/decisions/0001-record-architecture-decisions.md b/template/{% if sphinx %}docs{% endif %}/explanations/decisions/0001-record-architecture-decisions.md new file mode 100644 index 00000000..44d234ef --- /dev/null +++ b/template/{% if sphinx %}docs{% endif %}/explanations/decisions/0001-record-architecture-decisions.md @@ -0,0 +1,18 @@ +# 1. Record architecture decisions + +## Status + +Accepted + +## Context + +We need to record the architectural decisions made on this project. + +## Decision + +We will use Architecture Decision Records, as [described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). + +## Consequences + +See Michael Nygard's article, linked above. To create new ADRs we will copy and +paste from existing ones. diff --git a/template/{% if sphinx %}docs{% endif %}/explanations/decisions/0002-switched-to-python-copier-template.md b/template/{% if sphinx %}docs{% endif %}/explanations/decisions/0002-switched-to-python-copier-template.md new file mode 100644 index 00000000..66fe5d8b --- /dev/null +++ b/template/{% if sphinx %}docs{% endif %}/explanations/decisions/0002-switched-to-python-copier-template.md @@ -0,0 +1,28 @@ +# 2. Adopt python-copier-template for project structure + +## Status + +Accepted + +## Context + +We should use the following [python-copier-template](https://github.com/DiamondLightSource/python-copier-template). +The template will ensure consistency in developer +environments and package management. + +## Decision + +We have switched to using the template. + +## Consequences + +This module will use a fixed set of tools as developed in `python-copier-template` +and can pull from this template to update the packaging to the latest techniques. + +As such, the developer environment may have changed, the following could be +different: + +- linting +- formatting +- pip venv setup +- CI/CD diff --git a/template/{% if sphinx %}docs{% endif %}/genindex.md b/template/{% if sphinx %}docs{% endif %}/genindex.md new file mode 100644 index 00000000..73f1191b --- /dev/null +++ b/template/{% if sphinx %}docs{% endif %}/genindex.md @@ -0,0 +1,3 @@ +# Index + + diff --git a/template/{% if sphinx %}docs{% endif %}/genindex.rst b/template/{% if sphinx %}docs{% endif %}/genindex.rst deleted file mode 100644 index 93eb8b29..00000000 --- a/template/{% if sphinx %}docs{% endif %}/genindex.rst +++ /dev/null @@ -1,5 +0,0 @@ -API Index -========= - -.. - https://stackoverflow.com/a/42310803 diff --git a/template/{% if sphinx %}docs{% endif %}/how-to.md b/template/{% if sphinx %}docs{% endif %}/how-to.md new file mode 100644 index 00000000..6b161417 --- /dev/null +++ b/template/{% if sphinx %}docs{% endif %}/how-to.md @@ -0,0 +1,10 @@ +# How-to Guides + +Practical step-by-step guides for the more experienced user. + +```{toctree} +:maxdepth: 1 +:glob: + +how-to/* +``` diff --git a/template/{% if sphinx %}docs{% endif %}/how-to/contribute.md b/template/{% if sphinx %}docs{% endif %}/how-to/contribute.md new file mode 100644 index 00000000..f9c4ca1d --- /dev/null +++ b/template/{% if sphinx %}docs{% endif %}/how-to/contribute.md @@ -0,0 +1,2 @@ +```{include} ../../.github/CONTRIBUTING.md +``` \ No newline at end of file diff --git a/template/{% if sphinx %}docs{% endif %}/how-to/run-container.md.jinja b/template/{% if sphinx %}docs{% endif %}/how-to/run-container.md.jinja new file mode 100644 index 00000000..be7f61cf --- /dev/null +++ b/template/{% if sphinx %}docs{% endif %}/how-to/run-container.md.jinja @@ -0,0 +1,14 @@ +# Run in a container + +Pre-built containers with {\{repo_name}} and its dependencies already +installed are available on [Github Container Registry](https://ghcr.io/{{github_org}}/{{repo_name}}). + +## Starting the container + +To pull the container from github container registry and run: + +``` +$ docker run ghcr.io/{{github_org}}/{{repo_name}}:main --version +``` + +To get a released version, use a numbered release instead of `main`. diff --git a/template/{% if sphinx %}docs{% endif %}/index.md b/template/{% if sphinx %}docs{% endif %}/index.md new file mode 100644 index 00000000..730b3fdc --- /dev/null +++ b/template/{% if sphinx %}docs{% endif %}/index.md @@ -0,0 +1,56 @@ +--- +html_theme.sidebar_secondary.remove: true +--- + +```{include} ../README.md +:end-before: + +::::{grid} 2 +:gutter: 4 + +:::{grid-item-card} {material-regular}`directions_walk;2em` +```{toctree} +:maxdepth: 2 +tutorials +``` ++++ +Tutorials for installation and typical usage. New users start here. +::: + +:::{grid-item-card} {material-regular}`directions;2em` +```{toctree} +:maxdepth: 2 +how-to +``` ++++ +Practical step-by-step guides for the more experienced user. +::: + +:::{grid-item-card} {material-regular}`info;2em` +```{toctree} +:maxdepth: 2 +explanations +``` ++++ +Explanations of how it works and why it works that way. +::: + +:::{grid-item-card} {material-regular}`menu_book;2em` +```{toctree} +:maxdepth: 2 +reference +``` ++++ +Technical reference material including APIs and release notes. +::: + +:::: diff --git a/template/{% if sphinx %}docs{% endif %}/index.rst.jinja b/template/{% if sphinx %}docs{% endif %}/index.rst.jinja deleted file mode 100644 index 1d2d837c..00000000 --- a/template/{% if sphinx %}docs{% endif %}/index.rst.jinja +++ /dev/null @@ -1,29 +0,0 @@ -:html_theme.sidebar_secondary.remove: - -.. include:: ../README.rst - :end-before: when included in index.rst - -How the documentation is structured ------------------------------------ - -The documentation is split into 2 sections: - -.. grid:: 2 - - .. grid-item-card:: :material-regular:`person;4em` - :link: user/index - :link-type: doc - - The User Guide contains documentation on how to install and use {{ repo_name }}. - - .. grid-item-card:: :material-regular:`code;4em` - :link: developer/index - :link-type: doc - - The Developer Guide contains documentation on how to develop and contribute changes back to {{ repo_name }}. - -.. toctree:: - :hidden: - - user/index - developer/index diff --git a/template/{% if sphinx %}docs{% endif %}/reference.md b/template/{% if sphinx %}docs{% endif %}/reference.md new file mode 100644 index 00000000..6a7d085a --- /dev/null +++ b/template/{% if sphinx %}docs{% endif %}/reference.md @@ -0,0 +1,11 @@ +# Reference + +Technical reference material including APIs and release notes. + +```{toctree} +:maxdepth: 1 +:glob: + +reference/* +genindex +``` diff --git a/template/{% if sphinx %}docs{% endif %}/reference/api.md.jinja b/template/{% if sphinx %}docs{% endif %}/reference/api.md.jinja new file mode 100644 index 00000000..1497a8e8 --- /dev/null +++ b/template/{% if sphinx %}docs{% endif %}/reference/api.md.jinja @@ -0,0 +1,17 @@ +# API + +```{eval-rst} +.. automodule:: {{package_name}} + + ``{{package_name}}`` + ----------------------------------- +``` + +This is the internal API reference for {\{package_name}} + +```{eval-rst} +.. data:: {{package_name}}.__version__ + :type: str + + Version number as calculated by https://github.com/pypa/setuptools_scm +``` diff --git a/template/{% if sphinx %}docs{% endif %}/tutorials.md b/template/{% if sphinx %}docs{% endif %}/tutorials.md new file mode 100644 index 00000000..1fe66c54 --- /dev/null +++ b/template/{% if sphinx %}docs{% endif %}/tutorials.md @@ -0,0 +1,10 @@ +# Tutorials + +Tutorials for installation and typical usage. New users start here. + +```{toctree} +:maxdepth: 1 +:glob: + +tutorials/* +``` diff --git a/template/{% if sphinx %}docs{% endif %}/tutorials/installation.md.jinja b/template/{% if sphinx %}docs{% endif %}/tutorials/installation.md.jinja new file mode 100644 index 00000000..5d05aadc --- /dev/null +++ b/template/{% if sphinx %}docs{% endif %}/tutorials/installation.md.jinja @@ -0,0 +1,42 @@ +# Installation + +## Check your version of python + +You will need python 3.8 or later. You can check your version of python by +typing into a terminal: + +``` +$ python3 --version +``` + +## Create a virtual environment + +It is recommended that you install into a “virtual environment” so this +installation will not interfere with any existing Python software: + +``` +$ python3 -m venv /path/to/venv +$ source /path/to/venv/bin/activate +``` + +## Installing the library + +You can now use `pip` to install the library and its dependencies: + +``` +$ python3 -m pip install {{pypi_name}} +``` + +If you require a feature that is not currently released you can also install +from github: + +``` +$ python3 -m pip install git+{{repo_url}}.git +``` + +The library should now be installed and the commandline interface on your path. +You can check the version that has been installed by typing: + +``` +$ {{repo_name}} --version +``` diff --git a/template/{% if sphinx %}docs{% endif %}/user/explanations/docs-structure.rst b/template/{% if sphinx %}docs{% endif %}/user/explanations/docs-structure.rst deleted file mode 100644 index f25a09ba..00000000 --- a/template/{% if sphinx %}docs{% endif %}/user/explanations/docs-structure.rst +++ /dev/null @@ -1,18 +0,0 @@ -About the documentation ------------------------ - - :material-regular:`format_quote;2em` - - The Grand Unified Theory of Documentation - - -- David Laing - -There is a secret that needs to be understood in order to write good software -documentation: there isn't one thing called *documentation*, there are four. - -They are: *tutorials*, *how-to guides*, *technical reference* and *explanation*. -They represent four different purposes or functions, and require four different -approaches to their creation. Understanding the implications of this will help -improve most documentation - often immensely. - -`More information on this topic. `_ diff --git a/template/{% if sphinx %}docs{% endif %}/user/how-to/run-container.rst.jinja b/template/{% if sphinx %}docs{% endif %}/user/how-to/run-container.rst.jinja deleted file mode 100644 index 9f4a94c0..00000000 --- a/template/{% if sphinx %}docs{% endif %}/user/how-to/run-container.rst.jinja +++ /dev/null @@ -1,15 +0,0 @@ -Run in a container -================== - -Pre-built containers with {{ repo_name }} and its dependencies already -installed are available on `Github Container Registry -`_. - -Starting the container ----------------------- - -To pull the container from github container registry and run:: - - $ docker run ghcr.io/{{ github_org }}/{{ repo_name }}:main --version - -To get a released version, use a numbered release instead of ``main``. diff --git a/template/{% if sphinx %}docs{% endif %}/user/index.rst b/template/{% if sphinx %}docs{% endif %}/user/index.rst deleted file mode 100644 index 2c94a0c0..00000000 --- a/template/{% if sphinx %}docs{% endif %}/user/index.rst +++ /dev/null @@ -1,57 +0,0 @@ -User Guide -========== - -Documentation is split into four categories, also accessible from links in the -side-bar. - -.. grid:: 2 - :gutter: 4 - - .. grid-item-card:: :material-regular:`directions_walk;3em` - - .. toctree:: - :caption: Tutorials - :maxdepth: 1 - - tutorials/installation - - +++ - - Tutorials for installation and typical usage. New users start here. - - .. grid-item-card:: :material-regular:`directions;3em` - - .. toctree:: - :caption: How-to Guides - :maxdepth: 1 - - how-to/run-container - - +++ - - Practical step-by-step guides for the more experienced user. - - .. grid-item-card:: :material-regular:`info;3em` - - .. toctree:: - :caption: Explanations - :maxdepth: 1 - - explanations/docs-structure - - +++ - - Explanations of how the library works and why it works that way. - - .. grid-item-card:: :material-regular:`menu_book;3em` - - .. toctree:: - :caption: Reference - :maxdepth: 1 - - reference/api - ../genindex - - +++ - - Technical reference material including APIs and release notes. diff --git a/template/{% if sphinx %}docs{% endif %}/user/reference/api.rst.jinja b/template/{% if sphinx %}docs{% endif %}/user/reference/api.rst.jinja deleted file mode 100644 index 16693ee6..00000000 --- a/template/{% if sphinx %}docs{% endif %}/user/reference/api.rst.jinja +++ /dev/null @@ -1,14 +0,0 @@ -API -=== - -.. automodule:: {{ package_name }} - - ``{{ package_name }}`` - ----------------------------------- - -This is the internal API reference for {{ package_name }} - -.. data:: {{ package_name }}.__version__ - :type: str - - Version number as calculated by https://github.com/pypa/setuptools_scm diff --git a/template/{% if sphinx %}docs{% endif %}/user/tutorials/installation.rst.jinja b/template/{% if sphinx %}docs{% endif %}/user/tutorials/installation.rst.jinja deleted file mode 100644 index b1654402..00000000 --- a/template/{% if sphinx %}docs{% endif %}/user/tutorials/installation.rst.jinja +++ /dev/null @@ -1,38 +0,0 @@ -Installation -============ - -Check your version of python ----------------------------- - -You will need python 3.8 or later. You can check your version of python by -typing into a terminal:: - - $ python3 --version - - -Create a virtual environment ----------------------------- - -It is recommended that you install into a “virtual environment” so this -installation will not interfere with any existing Python software:: - - $ python3 -m venv /path/to/venv - $ source /path/to/venv/bin/activate - - -Installing the library ----------------------- - -You can now use ``pip`` to install the library and its dependencies:: - - $ python3 -m pip install {{ distribution_name }} - -If you require a feature that is not currently released you can also install -from github:: - - $ python3 -m pip install git+{{ repo_url }}.git - -The library should now be installed and the commandline interface on your path. -You can check the version that has been installed by typing:: - - $ {{ repo_name }} --version