Skip to content

Commit 360bf05

Browse files
cjolowiczcjolowicz
authoredApr 5, 2020
Add documentation for Cookiecutter (#39)
* [nox] Remove build directory before invoking Sphinx * [nox] Add docs session * [nox] Use sphinx-autobuild for interactive sessions * Ignore /docs/_build/ * Ignore /.nox/ * Ignore __pycache__/ * [nox] Treat warnings as errors * [nox] Run sphinx-build in nit-picky mode * [conf] Use a fixed sidebar * [conf] Increase sidebar width to 250px * [conf] Add logo to sidebar * [conf] Sort theme options * [conf] Add Sphinx configuration * [conf] Add GitHub banner and button * [conf] Use "true" instead of True for theme options * [conf] Fix logo location * [license] Add license * [index] Add master document * [CODE_OF_CONDUCT] Symlink into docs * [quickstart] Add Quickstart Guide * [guide] Add User Guide * [guide] Fix incorrect usage of git branch --remotes * Pin documentation build dependencies * Add Read the Docs configuration
·
2022.6.32020.4.15
1 parent f2996df commit 360bf05

11 files changed

+2499
-0
lines changed
 

‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
/.nox/
2+
/docs/_build/
3+
__pycache__/

‎.readthedocs.yml

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
version: 2
2+
sphinx:
3+
configuration: docs/conf.py
4+
formats: all
5+
python:
6+
version: 3.8
7+
install:
8+
- requirements: docs/requirements.txt

‎docs/CODE_OF_CONDUCT.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../CODE_OF_CONDUCT.md

‎docs/_static/Logo.png

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../Logo.png

‎docs/conf.py

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
"""Sphinx configuration."""
2+
from datetime import datetime
3+
4+
5+
project = "Hypermodern Python Cookiecutter"
6+
author = "Claudio Jolowicz"
7+
copyright = f"{datetime.now().year}, {author}"
8+
extensions = ["recommonmark"]
9+
html_static_path = ["_static"]
10+
html_theme_options = {
11+
"github_banner": "true",
12+
"github_button": "true",
13+
"github_count": "true",
14+
"github_user": "cjolowicz",
15+
"github_repo": "cookiecutter-hypermodern-python",
16+
"github_type": "star",
17+
"logo": "Logo.png",
18+
"logo_name": "true",
19+
"fixed_sidebar": "true",
20+
"sidebar_width": "250px",
21+
}

‎docs/guide.rst

+2,209
Large diffs are not rendered by default.

‎docs/index.rst

+81
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
Hypermodern Python Cookiecutter
2+
===============================
3+
4+
.. toctree::
5+
:hidden:
6+
:maxdepth: 1
7+
8+
Quickstart <quickstart>
9+
guide
10+
Code of Conduct <CODE_OF_CONDUCT>
11+
license
12+
Changelog <https://github.com/cjolowicz/cookiecutter-hypermodern-python/releases>
13+
14+
|Tests| |CalVer|
15+
16+
.. |Tests| image:: https://github.com/cjolowicz/cookiecutter-hypermodern-python/workflows/Tests/badge.svg
17+
:target: https://github.com/cjolowicz/cookiecutter-hypermodern-python/actions?workflow=Tests
18+
.. |CalVer| image:: https://img.shields.io/badge/calver-YYYY.MM.DD-22bfda.svg
19+
:target: http://calver.org/
20+
21+
Cookiecutter_ template for a Python package
22+
based on the `Hypermodern Python`_ article series.
23+
24+
25+
Usage
26+
-----
27+
28+
.. code:: console
29+
30+
$ cookiecutter gh:cjolowicz/cookiecutter-hypermodern-python \
31+
--checkout="2020.3.27"
32+
33+
34+
Features
35+
--------
36+
37+
.. include:: guide.rst
38+
:start-after: features-begin
39+
:end-before: features-end
40+
41+
42+
FAQ
43+
---
44+
45+
*What is this project about?*
46+
47+
The mission of this project is to
48+
enable current best practises
49+
through modern Python tooling.
50+
51+
*What makes this project different from other Python templates?*
52+
53+
This is a general-purpose template for Python libraries and applications.
54+
55+
Our goals are:
56+
57+
- Keep a focus on simplicity and minimalism
58+
- Promote code quality through automation
59+
- Provide reliable and repeatable processes
60+
61+
The project template is centered around the following tools:
62+
63+
- Poetry_ for packaging and dependency management
64+
- Nox_ for automation of checks and other development tasks
65+
- `GitHub Actions`_ for continuous integration and delivery
66+
67+
*Why is this Python template called "hypermodern"?*
68+
69+
Hypermodernism_ is a school of chess from a century ago.
70+
If this setup ever goes out of fashion,
71+
I can pretend it was my secret plan from the start.
72+
All images on the
73+
`associated blog <Hypermodern Python_>`__ show
74+
`outdated visions <Retrofuturism_>`__ of the future.
75+
76+
.. _`Hypermodernism`: https://en.wikipedia.org/wiki/Hypermodernism_(chess)
77+
.. _`Retrofuturism`: https://en.wikipedia.org/wiki/Retrofuturism
78+
79+
.. include:: guide.rst
80+
:start-after: references-begin
81+
:end-before: references-end

‎docs/license.rst

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
License
2+
=======
3+
4+
.. include:: ../LICENSE

‎docs/quickstart.rst

+142
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
Quickstart Guide
2+
================
3+
4+
Requirements
5+
------------
6+
7+
Install Cookiecutter_:
8+
9+
.. code:: console
10+
11+
$ pipx install cookiecutter
12+
13+
Install Poetry_ by downloading and running get-poetry.py_:
14+
15+
.. _`get-poetry.py`: https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py
16+
17+
.. code:: console
18+
19+
$ python get-poetry.py
20+
21+
Install Nox_:
22+
23+
.. code:: console
24+
25+
$ pipx install nox
26+
27+
pipx_ is preferred,
28+
but you can also install with ``pip install --user``.
29+
30+
It is recommended to set up Python 3.6, 3.7, and 3.8 using pyenv_.
31+
32+
33+
Creating a project
34+
------------------
35+
36+
Generate a Python project:
37+
38+
.. code:: console
39+
40+
$ cookiecutter gh:cjolowicz/cookiecutter-hypermodern-python \
41+
--checkout="2020.3.27"
42+
43+
Change to the root directory of your new project,
44+
and create a Git repository:
45+
46+
.. code:: console
47+
48+
$ git init
49+
$ git add .
50+
$ git commit
51+
52+
Local testing
53+
-------------
54+
55+
Run the full test suite:
56+
57+
.. code:: console
58+
59+
$ nox
60+
61+
List the available Nox sessions:
62+
63+
.. code:: console
64+
65+
$ nox --list-sessions
66+
67+
68+
Continuous Integration
69+
----------------------
70+
71+
GitHub
72+
~~~~~~
73+
74+
1. Sign up at GitHub_.
75+
2. Create an empty repository for your project.
76+
3. Follow the instructions to push an existing repository from the command line.
77+
78+
79+
PyPI
80+
~~~~
81+
82+
1. Sign up at PyPI_.
83+
2. Go to the Account Settings on PyPI,
84+
generate an API token, and copy it.
85+
3. Go to the repository settings on GitHub, and
86+
add a secret named ``PYPI_TOKEN`` with the token you just copied.
87+
88+
89+
TestPyPI
90+
~~~~~~~~
91+
92+
1. Sign up at TestPyPI_.
93+
2. Go to the Account Settings on TestPyPI,
94+
generate an API token, and copy it.
95+
3. Go to the repository settings on GitHub, and
96+
add a secret named ``TEST_PYPI_TOKEN`` with the token you just copied.
97+
98+
99+
Codecov
100+
~~~~~~~
101+
102+
1. Sign up at Codecov_, and install their GitHub app.
103+
2. Add your repository to Codecov.
104+
105+
106+
Read the Docs
107+
~~~~~~~~~~~~~
108+
109+
1. Sign up at `Read the Docs`_.
110+
2. Import your GitHub repository, using the button *Import a Project*.
111+
112+
113+
Releasing
114+
---------
115+
116+
1. Bump the version using `poetry version`_. Push to GitHub.
117+
2. Publish a GitHub Release.
118+
3. GitHub Action triggers the PyPI upload.
119+
120+
.. _`poetry version`: https://python-poetry.org/docs/cli/#version
121+
122+
Release notes are pre-filled with titles and authors of merged pull requests.
123+
124+
Use labels to group the pull requests into sections:
125+
126+
.. include:: guide.rst
127+
:start-after: table-release-drafter-sections-begin
128+
:end-before: table-release-drafter-sections-end
129+
130+
GitHub creates the ``bug``, ``enhancement``, and ``documentation`` labels for you.
131+
Create the remaining labels on the Issues tab of your GitHub repository.
132+
133+
134+
Caveats
135+
-------
136+
137+
When upgrading Sphinx or its extensions using Poetry,
138+
also update the requirements located in ``docs/requirements.txt`` for Read the Docs.
139+
140+
.. include:: guide.rst
141+
:start-after: references-begin
142+
:end-before: references-end

‎docs/requirements.txt

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
recommonmark==0.6.0
2+
sphinx==2.4.4
3+
sphinx-autobuild==0.7.1

‎noxfile.py

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
"""Nox sessions."""
2+
from pathlib import Path
3+
import shutil
4+
5+
import nox
6+
from nox.sessions import Session
7+
8+
9+
@nox.session
10+
def docs(session: Session) -> None:
11+
"""Build the documentation."""
12+
args = session.posargs or ["-W", "-n", "docs", "docs/_build"]
13+
14+
if session.interactive and not session.posargs:
15+
args.append("--open-browser")
16+
17+
builddir = Path("docs", "_build")
18+
if builddir.exists():
19+
shutil.rmtree(builddir)
20+
21+
session.install("-r", "docs/requirements.txt")
22+
23+
if session.interactive:
24+
session.run("sphinx-autobuild", *args)
25+
else:
26+
session.run("sphinx-build", *args)

0 commit comments

Comments
 (0)
Please sign in to comment.