Move from Sphinx to MkDocs for the cookiecutter package (#31)

Author: Florian Maas

.github/workflows/on-merge-to-main.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Documentation Test
         run: |
           source .venv/bin/activate
-          make docs-verify
+          make docs-test
 
   tox:
     runs-on: ubuntu-latest

.github/workflows/on-pull-request.yml

@@ -21,7 +21,7 @@ jobs:
       - name: Documentation Test
         run: |
           source .venv/bin/activate
-          make docs-verify
+          make docs-test
 
   tox:
     runs-on: ubuntu-latest

.github/workflows/on-release-main.yml

@@ -22,7 +22,7 @@ jobs:
       - name: Documentation Test
         run: |
           source .venv/bin/activate
-          make docs-verify
+          make docs-test
 
   tox:
     runs-on: ubuntu-latest

Makefile

@@ -41,12 +41,14 @@ publish: ## publish a release to pypi.
 
 build-and-publish: build publish ## Build and publish.
 
-docs-verify: ## Check if MkDocs build does not return warnings or errors
+docs-test: ## Test if documentation can be built without warnings or errors
 	@mkdocs build -s
 
-docs-serve: ## Build and serve the MkDocs documentation
+docs: ## Build and serve the documentation
 	@mkdocs serve
 
+.PHONY: docs	
+
 .PHONY: help
 
 help:

README.rst

@@ -65,7 +65,7 @@ Features
 +----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | **Release to Artifactory**                   | Release to `Artifactory <https://jfrog.com/artifactory>`_ by creating a new release on Github.                                                             |
 +----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| **Documentation with Sphinx**                | Automatically add documentation to your project and its code with `Sphinx <https://www.sphinx-doc.org/>`_.                                                 |
+| **Documentation with MkDocs**                | Automatically add documentation to your project and its code with `MkDocs <https://www.mkdocs.org/>`_.                                                     |
 +----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | **Tox testing**                              | Setup and CI/CD integration to easily test for different Python versions with `Tox <https://tox.wiki/>`_.                                                  |
 +----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -107,10 +107,13 @@ Then run the following commands, replacing ``<project-name>``, with the name tha
     git push -u origin main
 
 
-Finally, install the environment with ``make install``. 
+Finally, install the environment with `make install`. 
 
-If you want to deploy to Pypi or Artifactory automatically on each release, you need to set
-some secrets in your repository on Github. For more information, see `the documentation <https://fpgmaas.github.io/cookiecutter-poetry/features/releasing.html>`_.
+You are now ready to start development on your project! The CI/CD pipeline will be triggered when you open a pull
+request, merge to main, or when you create a new release.
+
+To finalize the set-up for publishing to PyPi or Artifactory through CI/CD, see `here <https://fpgmaas.github.io/cookiecutter-poetry/features/publishing/#set-up-for-pypi>`_. 
+For activating the automatic documentation with MkDocs, see `here <https://fpgmaas.github.io/cookiecutter-poetry/features/mkdocs/#enabling-the-documentation-on-github>`_.
 
 
 Acknowledgements

cookiecutter.json

@@ -7,7 +7,7 @@
     "project_description": "This is a template repository for Python projects that use Poetry for their dependency management.",
     "include_github_actions": ["y","n"],
     "publish_to": ["pypi", "artifactory", "none"],
-    "sphinx_docs": ["y", "n"],
+    "mkdocs": ["y", "n"],
     "tox": ["y","n"],
     "open_source_license": ["MIT license", "BSD license", "ISC license", "Apache Software License 2.0", "GNU General Public License v3", "Not open source"]
 }

docs/features.md

@@ -1,6 +1,5 @@
----
-title: CI/CD with Github actions
----
+
+# CI/CD with Github actions
 
 when `include_github_actions` is set to `"y"`, a `.github` directory is
 added with the following structure:
@@ -28,14 +27,21 @@ formatting.
 made on the `main` branch. In addition, `on-release-main.yml` also
 publishes the project to Pypi or Artifactory if `publish_to` is set to
 `"pypi"` or `"artifactory"`, and it builds and deploys the documentation
-if `sphinx_docs` is set to `"y"`. To learn more about these features,
-see `Releasing to Pypi or Artifactory <./releasing>`{.interpreted-text
-role="doc"} and `Documentation with Sphinx
-<./sphinx>`{.interpreted-text role="doc"}
+if `mkdocs` is set to `"y"`. To learn more about these features,
+see [Publishing to PyPi or Artifactory](./publishing.md) and [Documentation with MkDocs](./mkdocs.md) 
 
 Additionally, all workflows check for compatibility with multiple Python
 versions if `tox` is set to `"y"`.
 
+# How to trigger a release?
+
+To trigger a new release, navigate to your repository on GitHub, click ``Releases`` on the right, and then select `Draft
+a new release`. If you fail to find the button, you could also directly visit
+`https://github.com/<username>/<repository-name>/releases/new`.
+
+Give your release a title, and add a new tag in the form `*.*.*` where the
+`*`'s are alphanumeric. To finish, press `Publish release`.
+
 ## Example CI/CD Pipeline
 
 [![Example pipeline](https://raw.githubusercontent.com/fpgmaas/cookiecutter-poetry/main/static/images/pipeline.png)](https://raw.githubusercontent.com/fpgmaas/cookiecutter-poetry/main/static/images/pipeline.png)

docs/features/cicd.md

@@ -19,7 +19,6 @@ build-and-publish    Build and publish.
 docs-generate        convert docstrings to docs
 docs-build           Build the docs
 docs-open            Open the docs in the browser
-docs                 Generate, build and open the docs.
-docs-build-test      Test if the documentation can be built without errors.
+docs                 Build and serve the documentation
 docs-test            Test if the documentation can be generated and built without errors.
 ```

docs/features/makefile.md

@@ -0,0 +1,52 @@
+# Documentation with MkDocs
+
+
+If `mkdocs` is set to `"y"`, documentation of your project is
+automatically added using
+[MkDocs](https://www.mkdocs.org/). Next to that, if
+`"include_github_actions"` is set to `"y"`, the documentation is
+automatically deployed to your `gh-pages` branch, and made available at
+`https://<github_handle>.github.io/<project_name>/`.
+
+To view the documentation locally, simply run
+
+``` bash
+make docs
+```
+
+This command will generate, and build your documentation, and start the server locally so you can access it at 
+<http://localhost:8000>.
+
+## Enabling the documentation on GitHub
+
+To enable your documentation on GitHub, first create a [new release](./cicd.md#how-to-trigger-a-release).
+
+Then, in your repository, navigate to ``Settings > Code and Automation > Pages``. If you succesfully created a new release,
+you should see a notification saying `` Your site is ready to be published at https://<author_github_handle>.github.io/<project_name>/``.
+
+To finalize deploying your documentation, under ``Source``, select the branch ``gh-pages``. Your documentation should then be live within a few minutes.
+
+## Documenting docstrings
+
+The generated project also converts all
+your docstrings into legible documentation. By default, the project is
+configured to work with
+[google](https://google.github.io/styleguide/pyguide.html) style
+docstrings.
+
+An example of a Google style docstring:
+
+``` python
+def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
+"""Example function with PEP 484 type annotations.
+
+Args:
+    param1: The first parameter.
+    param2: The second parameter.
+
+Returns:
+    The return value. True for success, False otherwise.
+```
+
+For more examples, see
+[here](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).