diff --git a/.github/CONTRIBUTING.rst b/.github/CONTRIBUTING.md similarity index 69% rename from .github/CONTRIBUTING.rst rename to .github/CONTRIBUTING.md index a563a4e4..c7f5a00b 100644 --- a/.github/CONTRIBUTING.rst +++ b/.github/CONTRIBUTING.md @@ -1,5 +1,4 @@ -Contributing to the project -=========================== +# Contributing to the project TODO diff --git a/docs/explanations/decisions.rst b/docs/explanations/decisions.rst deleted file mode 100644 index 5841e6ea..00000000 --- a/docs/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/docs/explanations/decisions/0001-record-architecture-decisions.rst b/docs/explanations/decisions/0001-record-architecture-decisions.rst deleted file mode 100644 index b2d3d0fe..00000000 --- a/docs/explanations/decisions/0001-record-architecture-decisions.rst +++ /dev/null @@ -1,26 +0,0 @@ -1. Record architecture decisions -================================ - -Date: 2022-02-18 - -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/docs/explanations/decisions/0002-switched-to-pip-skeleton.md.jinja b/docs/explanations/decisions/0002-switched-to-pip-skeleton.md similarity index 92% rename from docs/explanations/decisions/0002-switched-to-pip-skeleton.md.jinja rename to docs/explanations/decisions/0002-switched-to-pip-skeleton.md index 6468ed0e..00490a29 100644 --- a/docs/explanations/decisions/0002-switched-to-pip-skeleton.md.jinja +++ b/docs/explanations/decisions/0002-switched-to-pip-skeleton.md @@ -8,7 +8,7 @@ Accepted ## Context -We should use the following [python_copier_template](https://github.com/DiamondLightSource/python_copier_template). +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. diff --git a/docs/explanations/structure.rst b/docs/explanations/structure.md similarity index 79% rename from docs/explanations/structure.rst rename to docs/explanations/structure.md index 66766c2d..c6bc21e0 100644 --- a/docs/explanations/structure.rst +++ b/docs/explanations/structure.md @@ -1,10 +1,8 @@ -Skeleton Project Structure -========================== +# Skeleton Project Structure The skeleton project has the following folders at the root level. -src ---- +## src This folder contains the source code for the project. Typically this contains a single folder with the package name for the project and the @@ -12,38 +10,32 @@ folder contains python modules files. See `src` for details. -tests ------ +## tests This folder holds all of the tests that will be run by pytest, both locally and in CI. See `using pytest` -docs ----- +## docs This folder contains the source for sphinx documentation. See `documentation structure` for details. -.github -------- +## .github Configuration for the Continuous Integration Workflow on github -VSCode specific folders ------------------------ +## VSCode specific folders -.devcontainer -~~~~~~~~~~~~~ +### .devcontainer Configuration for running the developer container for this project in VSCode. -.vscode -~~~~~~~ +### .vscode VSCode settings for this project. diff --git a/docs/how-to/build-docs.rst b/docs/how-to/build-docs.rst deleted file mode 100644 index 79e3f780..00000000 --- a/docs/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 browse:: - - $ 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/ \ No newline at end of file diff --git a/docs/how-to/contribute.md b/docs/how-to/contribute.md index be3b762a..f9c4ca1d 100644 --- a/docs/how-to/contribute.md +++ b/docs/how-to/contribute.md @@ -1 +1,2 @@ -.. include:: ../../../.github/CONTRIBUTING.md +```{include} ../../.github/CONTRIBUTING.md +``` \ No newline at end of file diff --git a/docs/how-to/contribute.rst b/docs/how-to/contribute.rst deleted file mode 100644 index 65b72c8e..00000000 --- a/docs/how-to/contribute.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../.github/CONTRIBUTING.rst diff --git a/docs/how-to/dev-install.rst b/docs/how-to/dev-install.rst deleted file mode 100644 index 111b4fe7..00000000 --- a/docs/how-to/dev-install.rst +++ /dev/null @@ -1,53 +0,0 @@ -Setup Developer Environment -=========================== - -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/DiamondLightSource/python3-pip-skeleton-cli.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 python3-pip-skeleton-cli - $ python3 -m venv venv - $ source venv/bin/activate - $ pip install -c dev-requirements.txt -e .[dev] - - .. tab-item:: VSCode devcontainer - - .. code:: - - $ code python3-pip-skeleton-cli - # Click on 'Reopen in Container' when prompted - # Open a new terminal - -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: - -- `./build-docs` -- `./run-tests` -- `./static-analysis` -- `./lint` diff --git a/docs/how-to/excalidraw.rst b/docs/how-to/excalidraw.rst deleted file mode 100644 index 5d733cec..00000000 --- a/docs/how-to/excalidraw.rst +++ /dev/null @@ -1,18 +0,0 @@ -How to embed Excalidraw diagrams -================================ - -Start off by creating your diagram in https://excalidraw.com - -.. raw:: html - :file: ../images/excalidraw-example.svg - -Click 'Save as image' and make sure the 'Embed scene' checkbox is enabled. This is required for loading your image back into Excalidraw should you wish to make changes later on. Name your file and export to SVG, saving it inside ``docs/images``. - -Add the following to embed it inside your documentation:: - - .. raw:: html - :file: ../images/my-diagram.excalidraw.svg - -It is preferred to use the above convention over ``.. image::`` in order to retain the font used by Excalidraw. - -Rebuild the docs and open the resulting html inside a browser. \ No newline at end of file diff --git a/docs/how-to/lint.rst b/docs/how-to/lint.rst deleted file mode 100644 index 8f4e92db..00000000 --- a/docs/how-to/lint.rst +++ /dev/null @@ -1,41 +0,0 @@ -Run linting using pre-commit -============================ - -Code linting is handled by black_, flake8_ and isort_ 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 isort:: - - $ isort . - -If you get any flake8 issues you will have to fix those manually. - -VSCode support --------------- - -The ``.vscode/settings.json`` will run black and isort formatters as well as -flake8 checking on save. Issues will be highlighted in the editor window. - - diff --git a/docs/how-to/make-release.rst b/docs/how-to/make-release.rst deleted file mode 100644 index b8e02e9b..00000000 --- a/docs/how-to/make-release.rst +++ /dev/null @@ -1,19 +0,0 @@ -Make a release -============== - -To make a new release, please follow this checklist: - -- Ensure that you have previously followed `./pypi` -- 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. - -A new release will be made and the wheel and sdist uploaded to PyPI. - -.. _release: https://github.com/DiamondLightSource/python3-pip-skeleton-cli/releases \ No newline at end of file diff --git a/docs/how-to/run-tests.rst b/docs/how-to/run-tests.rst deleted file mode 100644 index 03247816..00000000 --- a/docs/how-to/run-tests.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. _using pytest: - -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:: - - $ pytest - -When you have some fully working tests then you can run it with coverage:: - - $ tox -e pytest-cov - -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/docs/how-to/static-analysis.rst b/docs/how-to/static-analysis.rst deleted file mode 100644 index 065920e1..00000000 --- a/docs/how-to/static-analysis.rst +++ /dev/null @@ -1,8 +0,0 @@ -Run static analysis using mypy -============================== - -Static type analysis is done with mypy_. 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 mypy diff --git a/docs/how-to/update-requirements.rst b/docs/how-to/update-requirements.rst deleted file mode 100644 index 89639623..00000000 --- a/docs/how-to/update-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/docs/how-to/update-template.rst b/docs/how-to/update-template.rst deleted file mode 100644 index db9e7ce1..00000000 --- a/docs/how-to/update-template.rst +++ /dev/null @@ -1,14 +0,0 @@ -How to update to the latest skeleton structure -============================================== - -If you used the commandline tool to create your repo (or adopt the skeleton -structure in an existing repo) some time ago, there may be some changes to the -structure that you could pick up. You can optionally check what differences -these changes make to the files by doing:: - - $ git fetch https://github.com/DiamondLightSource/python3-pip-skeleton main - $ git diff ...FETCH_HEAD - -To merge the changes in do:: - - $ git pull https://github.com/DiamondLightSource/python3-pip-skeleton main diff --git a/docs/reference/standards.rst b/docs/reference/standards.rst deleted file mode 100644 index b78a719e..00000000 --- a/docs/reference/standards.rst +++ /dev/null @@ -1,64 +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 -- flake8_ for style checks -- isort_ for import ordering -- mypy_ 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` \ No newline at end of file diff --git a/docs/tutorials/create-new.rst b/docs/tutorials/create-new.md similarity index 63% rename from docs/tutorials/create-new.rst rename to docs/tutorials/create-new.md index 4c42bd27..af796eb9 100644 --- a/docs/tutorials/create-new.rst +++ b/docs/tutorials/create-new.md @@ -1,7 +1,6 @@ -Creating a new repo from the template -===================================== +# Creating a new repo from the template -Once you have followed the `./installation` tutorial, you can use ``copier`` +Once you have followed the [](./installation) tutorial, you can use `copier` to make a new project from the template:: $ mkdir /path/to/my-project @@ -13,22 +12,19 @@ This will: - Expand the template with the answers give - Record the answers in the project so they can be used in later updates -Uploading to GitHub -------------------- +## Uploading to GitHub You can now create a new blank project at . Choose the same GitHub owner and repo name that you answered in the questions earlier. GitHub will now give you the commands needed to upload your repo from GitHub -Setings -------- +## Setings -You can now go to the ``Settings`` and set: +You can now go to the `Settings` and set: - The project description to match the answer you gave - Enable Pages if you chose to use sphinx for your documentation -Getting started with your new repo ----------------------------------- +## Getting started with your new repo -You can now `../how-to/dev-install`, and then follow some of the other `../how-to`. +You can now [](./dev-install), and then follow some of the other [](../how-to). diff --git a/docs/tutorials/dev-install.md.jinja b/docs/tutorials/dev-install.md similarity index 94% rename from docs/tutorials/dev-install.md.jinja rename to docs/tutorials/dev-install.md index f47e439e..e6ad0796 100644 --- a/docs/tutorials/dev-install.md.jinja +++ b/docs/tutorials/dev-install.md @@ -8,7 +8,7 @@ environment setup, so you can run the tests locally. First clone the repository locally using [Git](https://git-scm.com/downloads): ``` -git clone git://github.com/{{github_org}}/{{repo_name}}.git +git@github.com:DiamondLightSource/python-copier-template.git ``` ## Install dependencies