Merge pull request #13 from claui/documentation

Add man page

.github/workflows/ci.yml

@@ -60,3 +60,6 @@ jobs:
 
       - name: Run unit tests
         run: poetry run poe tests
+
+      - name: Run man page generator
+        run: poetry run poe doc

CONTRIBUTING.md

@@ -166,12 +166,18 @@ act
 
 ### Generating project documentation
 
-To generate project documentation and open it in your browser, run:
+To generate project documentation, run:
 
-```
+```sh
 poetry run poe doc
 ```
 
+To open the generated documentation with `man`, run:
+
+```sh
+poetry run poe man
+```
+
 ## Maintenance
 
 ### Refreshing dependencies

README.md

@@ -1,7 +1,7 @@
 # pyproject-patcher
 
-This package is an attempt to make it a little easier to patch
-`pyproject.toml` in place.
+This Python package is an attempt to make it a little easier to
+patch `pyproject.toml` in place.
 
 It is mainly useful for maintainers of system packages.  
 If you’re not a maintainer of system packages, or if you don’t know

USAGE.md

@@ -1,7 +1,20 @@
 <!-- markdownlint-configure-file { "MD041": { "level": 1 } } -->
 
+# Description
+
+This Python package is an attempt to make it a little easier to
+patch `pyproject.toml` in place.
+
+It is mainly useful for maintainers of system packages.  
+If you’re not a maintainer of system packages, or if you don’t know
+what that means, then `pyproject-patcher` is probably not for you.
+
 # Examples
 
+## Recommended import statement
+
+The following examples all assume the following import statement:
+
 ```py
 from pyproject_patcher import patch_in_place
 ```

doc/sphinx/conf.py

@@ -0,0 +1,37 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'pyproject-patcher'
+author = 'Claudia Pellegrino <clau@tiqua.de>'
+description = 'Collection of convenience functions to patch `pyproject.toml` in place'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'myst_parser',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+]
+
+myst_enable_extensions = [
+    'deflist',
+]
+
+templates_path = []
+exclude_patterns = []
+
+# Man page output
+
+man_pages = [(
+    'index',
+    project.lower(),
+    description,
+    [author],
+    3,
+)]

doc/sphinx/index.rst

@@ -0,0 +1,9 @@
+Welcome to pyproject-patcher's documentation!
+=============================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+.. include:: ../../USAGE.md
+   :parser: myst_parser.sphinx_

pyproject.toml

@@ -71,6 +71,8 @@ html.cmd = "pdoc pyproject_patcher !pyproject_patcher.settings"
 html.help = "Browse HTML documentation"
 linter.cmd = "pylint --enable-all-extensions pyproject_patcher"
 linter.help = "Check for style violations"
+man.cmd = "man build/man/pyproject-patcher.3"
+man.help = "Open manual page"
 tests.cmd = "pytest"
 tests.help = "Run test suite"
 typecheck.cmd = "mypy"