Skip to content

Commit a43457e

Browse files
author
Florian Maas
authored
Autodocs (fpgmaas#14)
* Added the option to add Sphinx documentation to the template
1 parent 86b3c62 commit a43457e

File tree

17 files changed

+241
-57
lines changed

17 files changed

+241
-57
lines changed

‎README.rst

+21-20
Original file line numberDiff line numberDiff line change
@@ -43,25 +43,27 @@ This is a `cookiecutter <https://github.com/cookiecutter/cookiecutter>`_ reposit
4343
Features
4444
--------
4545

46-
+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
47-
| Feature | Description |
48-
+===========================================+=================================================================================================================+
49-
| **Poetry** | Generates a poetry environment file, ready to be installed with a single command. |
50-
+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
51-
| **Makefile** | A makefile with pre-configured commands, type `make help` to list the options. |
52-
+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
53-
| **Pytest** | Adds a pytest template. |
54-
+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
55-
| **Formatting** | Adds code formatting with ``isort``, ``black`` and ``flake8``. |
56-
+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
57-
| **Pyenv** (Optional) | Automatically adds a ``.python-version`` file for `pyenv <https://github.com/pyenv/pyenv>`_ support. |
58-
+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
59-
| **CI/CD with Github actions** (Optional) | Adds Github actions that run the formatting checks and unittests for pull requests and when merged to `main`. |
60-
+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
61-
| **Release to Pypi** (Optional) | Release to `Pypi <https://pypi.org>`_ manually, or by creating a new release on Github. |
62-
+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
63-
| **Release to Artifactory** (Optional) | Release to `Artifactory <https://jfrog.com/artifactory>`_ manually, or by creating a new release on Github. |
64-
+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
46+
+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
47+
| Feature | Description |
48+
+==============================================+=================================================================================================================+
49+
| **Poetry** | Generates a poetry environment file, ready to be installed with a single command. |
50+
+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
51+
| **Makefile** | A makefile with pre-configured commands, type `make help` to list the options. |
52+
+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
53+
| **Pytest** | Adds a pytest template. |
54+
+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
55+
| **Formatting** | Adds code formatting with ``isort``, ``black`` and ``flake8``. |
56+
+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
57+
| **Pyenv** (Optional) | Automatically adds a ``.python-version`` file for `pyenv <https://github.com/pyenv/pyenv>`_ support. |
58+
+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
59+
| **CI/CD with Github actions** (Optional) | Adds Github actions that run the formatting checks and unittests for pull requests and when merged to `main`. |
60+
+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
61+
| **Release to Pypi** (Optional) | Release to `Pypi <https://pypi.org>`_ manually, or by creating a new release on Github. |
62+
+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
63+
| **Release to Artifactory** (Optional) | Release to `Artifactory <https://jfrog.com/artifactory>`_ manually, or by creating a new release on Github. |
64+
+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
65+
| **Documentation with Sphinx** (Optional) | Automatically build documentation of your project and it's code with `Sphinx <https://www.sphinx-doc.org/>`_. |
66+
+----------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
6567

6668
Quickstart
6769
------------
@@ -91,7 +93,6 @@ Run the following commands, replacing ``<project-name>``, with the name that you
9193
git remote add origin [email protected]:<github_author_handle>/<project_name>.git
9294
git push -u origin main
9395
94-
Note: If this raises an
9596
9697
Finally, install the environment with ``make install``.
9798

‎cookiecutter.json

+1
Original file line numberDiff line numberDiff line change
@@ -9,5 +9,6 @@
99
"include_pyenv_local_file": ["y","n"],
1010
"include_github_actions": ["y","n"],
1111
"publish_to": ["pypi", "artifactory", "none"],
12+
"sphinx_docs": ["y", "n"],
1213
"open_source_license": ["MIT license", "BSD license", "ISC license", "Apache Software License 2.0", "GNU General Public License v3", "Not open source"]
1314
}

‎docs/_static/css/custom.css

+11
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,14 @@
11
.wy-table-responsive table td, .wy-table-responsive table th {
22
white-space: inherit;
3+
}
4+
5+
.index-visit-on-github>p{
6+
display: flex;
7+
justify-content: flex-start;
8+
align-items: center;
9+
}
10+
11+
.index-visit-on-github a {
12+
font-size: 24px;
13+
margin-left: 10px;
314
}

‎docs/feature_details.rst

+20
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,12 @@ A ``Makefile`` is available with the following commands:
4949
+------------------------+-----------------------------------------------------------------------------------------------------------+
5050
| ``build-and-publish`` | Available if ``publish_to`` is set to ``"pypi"`` or ``"artifactory"``. Build and publish. |
5151
+------------------------+-----------------------------------------------------------------------------------------------------------+
52+
| ``docs-generate`` | Convert docstrings to ``rst``-files to prepare for building documentation with Sphinx. |
53+
+------------------------+-----------------------------------------------------------------------------------------------------------+
54+
| ``docs-build`` | Build documentation with sphinx. |
55+
+------------------------+-----------------------------------------------------------------------------------------------------------+
56+
| ``docs`` | Generate and build documentation with Sphinx, and directly open the documentation in the browser. |
57+
+------------------------+-----------------------------------------------------------------------------------------------------------+
5258

5359
Pytest
5460
----------
@@ -111,3 +117,17 @@ to set-up the environment, run the tests, and check the code formatting.
111117
``on-release-main.yml`` does all of the former whenever a new release is made on the ``main`` branch. To learn more about releasing,
112118
see :doc:`Releasing to Pypi or Artifactory <./releasing>`.
113119

120+
121+
Release to Pypi (Optional)
122+
----------------------------
123+
124+
See :doc:`Releasing to Pypi or Artifactory <./releasing>`
125+
126+
Release to Artifactory (Optional)
127+
----------------------------------
128+
129+
See :doc:`Releasing to Pypi or Artifactory <./releasing>`
130+
131+
Documentation with Sphinx (Optional)
132+
------------------------------------
133+

‎docs/images/GitHub-Mark-120px-plus.png

4.17 KB
Loading

‎docs/index.rst

+7
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,13 @@ cookiecutter-poetry
3232
This is the documentation of `cookiecutter-poetry <https://github.com/fpgmaas/cookiecutter-poetry>`_, a `cookiecutter <https://github.com/cookiecutter/cookiecutter>`_ repository to
3333
generate the file structure for a Python project that uses `Poetry <https://python-poetry.org/>`_ for its dependency management.
3434

35+
.. container:: index-visit-on-github
36+
37+
|pic1| `Visit on Github <https://github.com/fpgmaas/cookiecutter-poetry>`_
38+
39+
.. |pic1| image:: ./images/GitHub-Mark-120px-plus.png
40+
:width: 40
41+
:target: https://github.com/fpgmaas/cookiecutter-poetry
3542

3643
Getting Started
3744
---------------

‎docs/prompt_arguments.rst

+10-5
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ a prompt will start which enables you to configure your repository. The prompt v
1414
Your full name.
1515

1616
**email**
17-
Your email address
17+
Your email address.
1818

1919
**github_author_handle**
2020
Your github handle, i.e. ``<handle>`` in ``https://github.com/<handle>``
@@ -23,7 +23,8 @@ a prompt will start which enables you to configure your repository. The prompt v
2323
Your project name. Should be equal to the name of your repository and it should only contain alphanumeric characters and ``-``'s.
2424

2525
**project_slug**
26-
The project slug, will default to the ``project_name`` with all ``-``'s replaced with ``_``. This will be how you import your code later, e.g.
26+
The project slug, will default to the ``project_name`` with all ``-``'s replaced with ``_``.
27+
This will be how you import your code later, e.g.
2728

2829
.. code-block:: python
2930
@@ -42,10 +43,14 @@ a prompt will start which enables you to configure your repository. The prompt v
4243
``"y"`` or ``"n"``. Adds a ``.github`` directory with various actions and workflows to setup the environment and run code formatting checks and unittests.
4344

4445
**publish_to**
45-
``"pypi"``, ``"artifactory"``, or ``"none"``. Adds functionality to the ``Makefile`` and Github workflows to make
46-
publishing your code as simple as creating a new release release on Github.
46+
``"pypi"``, ``"artifactory"``, or ``"none"``. Adds functionality to the ``Makefile`` and Github workflows to make publishing
47+
your code as simple as creating a new release release on Github.
4748
For more info, see :doc:`Releasing to Pypi or Artifactory <./releasing>`.
4849

50+
**sphinx_docs**
51+
``"y"`` or ``"n"``. Adds `sphinx <https://www.sphinx-doc.org/en/master/>`_` documentation to your project. This includes automatically parsing your
52+
docstrings and adding them to the documentation. Documentation will be deployed to the ``gh-pages`` branch.
53+
4954
**open_source_license**
5055
Choose a `license <https://choosealicense.com/>`_. Options: ``["1. MIT License", "2. BSD license", "3. ISC license",
51-
"4. Apache Software License 2.0", "5. GNU General Public License v3", "6. Not open source"]``
56+
"4. Apache Software License 2.0", "5. GNU General Public License v3", "6. Not open source"]``

‎{{cookiecutter.project_name}}/.github/workflows/on-release-main.yml

+28-1
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ on:
66
name: release-main
77

88
jobs:
9+
910
quality:
1011
runs-on: ubuntu-latest
1112
steps:
@@ -52,4 +53,30 @@ jobs:
5253
ARTIFACTORY_PASSWORD: ${{ secrets.ARTIFACTORY_PASSWORD }}
5354
RELEASE_VERSION: ${{ steps.vars.outputs.tag }}
5455
{%- endraw -%}
55-
{%- endif %}
56+
{%- endif %}
57+
58+
{% if cookiecutter.publish_to == "pypi" -%}
59+
documentation:
60+
needs: Release
61+
runs-on: ubuntu-latest
62+
steps:
63+
64+
- name: Check out
65+
uses: actions/checkout@v2
66+
67+
- name: Set up the environment
68+
uses: ./.github/workflows/setup-poetry-env
69+
70+
- name: Generate documentation
71+
run: |
72+
source .venv/bin/activate
73+
make docs-build
74+
75+
- name: Deploy documentation to GitHub pages
76+
uses: peaceiris/actions-gh-pages@v3
77+
with:
78+
{% raw -%}
79+
github_token: ${{ secrets.GITHUB_TOKEN }}
80+
publish_dir: ./docs/_build
81+
{%- endraw -%}
82+
{% endif -%}

‎{{cookiecutter.project_name}}/Makefile

+13
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,19 @@ publish: ## Publish to the Artifactory repository using poetry. Requires ARTIFAC
4747
build-and-publish: build publish ## Build and publish.
4848
{%- endif %}
4949

50+
{% if cookiecutter.sphinx_docs == "y" -%}
51+
docs-generate: ## convert docstrings to docs
52+
@sphinx-apidoc -o docs/source/ {{cookiecutter.project_slug}}
53+
54+
docs-build: ## Build the docs
55+
@sphinx-build -b html docs docs/_build
56+
57+
docs-open: ## Build the docs
58+
@open docs/_build/index.html
59+
60+
docs: docs-generate docs-build docs-open ## Generate, build and open the docs.
61+
{% endif -%}
62+
5063
.PHONY: help
5164

5265
help:

‎{{cookiecutter.project_name}}/README.md

-31
This file was deleted.

‎{{cookiecutter.project_name}}/README.rst

+54
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
==================================
2+
{{cookiecutter.project_name}}
3+
==================================
4+
5+
.. image:: https://img.shields.io/github/v/release/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}
6+
:target: https://img.shields.io/github/v/release/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}
7+
:alt: Release
8+
9+
.. image:: https://img.shields.io/github/workflow/status/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}/merge-to-main
10+
:target: https://img.shields.io/github/workflow/status/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}/merge-to-main
11+
:alt: Build status
12+
13+
.. image:: https://img.shields.io/github/commit-activity/m/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}
14+
:target: https://img.shields.io/github/commit-activity/m/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}
15+
:alt: Commit activity
16+
17+
.. image:: https://img.shields.io/badge/docs-gh--pages-blue
18+
:target: https://{{cookiecutter.github_author_handle}}.github.io/{{cookiecutter.project_name}}/
19+
:alt: Docs
20+
21+
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
22+
:target: https://github.com/psf/black
23+
:alt: Code style with black
24+
25+
.. image:: https://img.shields.io/badge/%20imports-isort-%231674b1
26+
:target: https://pycqa.github.io/isort/
27+
:alt: Imports with isort
28+
29+
.. image:: https://img.shields.io/github/license/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}
30+
:target: https://img.shields.io/github/license/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}
31+
:alt: License
32+
33+
{{cookiecutter.project_description}}
34+
35+
36+
Releasing a new version
37+
-----------------------------
38+
39+
{% if cookiecutter.publish_to == "pypi" -%}
40+
- Create an API Token on `Pypi <https://pypi.org/>`_
41+
- Add the API Token to your projects secrets with the name ``PYPI_TOKEN`` by visiting `this page <https://github.com/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}/settings/secrets/actions/new>`_.
42+
- Create a `new release <https://github.com/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}/releases/new>`_ on Github. Create a new tag in the form ``*.*.*``.
43+
44+
For more details, see `here <https://fpgmaas.github.io/cookiecutter-poetry/releasing.html>`_.
45+
{%- elif cookiecutter.publish_to == "artifactory" -%}
46+
- Add the `ARTIFACTORY_URL`, `ARTIFACTORY_USERNAME`, and `ARTIFACTORY_PASSWORD` to your projects secrets by visiting `this page <https://github.com/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}/settings/secrets/actions/new>`_.
47+
- Create a `new release <https://github.com/{{cookiecutter.github_author_handle}}/{{cookiecutter.project_name}}/releases/new>`_ on Github. Create a new tag in the form ``*.*.*``.
48+
49+
For more details, see `here <https://fpgmaas.github.io/cookiecutter-poetry/releasing.html>`_.
50+
{%- endif %}
51+
52+
---------
53+
54+
Repository initiated with `fpgmaas/cookiecutter-poetry <https://github.com/fpgmaas/cookiecutter-poetry>`_

‎{{cookiecutter.project_name}}/docs/.DS_Store

6 KB
Binary file not shown.

0 commit comments

Comments
 (0)