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

.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/cicd.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/makefile.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/mkdocs.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).

docs/features/publishing.md

@@ -6,9 +6,9 @@
 When `publish_to` is set to `"pypi"` or `"artifactory"`, the
 `on-release-main.yml` workflow publishes the code to
 [Pypi](https://pypi.org) or [Artifactory](https://jfrog.com/artifactory)
-respectively whenever a new release is made.
+respectively whenever a [new release](./cicd.md#how-to-trigger-a-release) is made.
 
-Before you can trigger the release workflow, you need to add some secrets to your github repository so
+Before you can succesfully publish your project from the release workflow, you need to add some secrets to your github repository so
 they can be used as environment variables.
 
 ## Set-up for Pypi
@@ -26,24 +26,15 @@ field for the Github secret in your first tab, and you're all set!
 In order to release to `Artifactory`, visit your Artifactory
 instance and open `Quick setup`. You should see something like this:
 
-![image](../static/artifactory.png){width="700px"}
+![image](../static/artifactory.png)
 
 You should add these as secrets to your repository with the names
 `ARTIFACTORY_URL`, `ARTIFACTORY_USERNAME` and `ARTIFACTORY_PASSWORD`
 respectively. To do so, in your Github repository, navigate to
 `Settings > Secrets > Actions` and create a secret by pressing
 `New repository secret` to add the secrets one by one.
 
-# 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`.
-
-# Releasing locally
+## Publishing from your local machine
 
 It is also possible to release locally, although it is not recommended.
 To do so, set the repository secrets listed in the sections above as

docs/index.md

@@ -1,19 +1,23 @@
 
 # Cookiecutter Poetry
 
+[![Release](https://img.shields.io/github/v/release/fpgmaas/cookiecutter-poetry)](https://pypi.org/project/cookiecutter-poetry/)
+[![Build status](https://img.shields.io/github/workflow/status/fpgmaas/cookiecutter-poetry/merge-to-main)](https://img.shields.io/github/workflow/status/fpgmaas/cookiecutter-poetry/merge-to-main)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/cookiecutter-poetry)](https://pypi.org/project/cookiecutter-poetry/)
+[![License](https://img.shields.io/github/license/fpgmaas/cookiecutter-poetry)](https://img.shields.io/github/license/fpgmaas/cookiecutter-poetry)
 
 This is a [cookiecutter](https://github.com/cookiecutter/cookiecutter)
 repository to generate the file structure for a Python project that uses
 [Poetry](https://python-poetry.org/) for its dependency management. 
 
 A project generated with ``cookiecutter-poetry`` supports the following features:
 
-- [Poetry](https://python-poetry.org/) for dependency management.
+- [Poetry](https://python-poetry.org/), obviously.
 - CI/CD with [GitHub Actions](https://github.com/features/actions)
 - Formatting with [black](https://pypi.org/project/black/) and [isort](https://pycqa.github.io/isort/index.html)
 - Publishing to [Pypi](https://pypi.org) or [Artifactory](https://jfrog.com/artifactory) by creating a new release on GitHub.
 - Testing with [pytest](https://docs.pytest.org/en/7.1.x/)
-- Documentation with [sphinx](https://www.sphinx-doc.org/en/master/)
+- Documentation with [MkDocs](https://www.mkdocs.org/)
 - Compatibility testing with [Tox](https://tox.wiki/en/latest/)
 
 An example of a repository generated with this package can be found [here](https://github.com/fpgmaas/cookiecutter-poetry-example).
@@ -51,10 +55,9 @@ git push -u origin main
 
 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](./features/publishing.md#set-up-for-pypi). For activating the automatic documentation with MkDocs, see [here](./features/mkdocs.md#enabling-the-documentation-on-github). 
 
 ## Acknowledgements
 

docs/prompt_arguments.md

@@ -49,9 +49,9 @@ simple as creating a new release release on Github. For more info,
 see
 [Publishing to Pypi or Artifactory](./features/publishing.md).
 
-**sphinx_docs**
+**mkdocs**
 
-`"y"` or `"n"`. Adds [Sphinx](https://www.sphinx-doc.org/en/master/)
+`"y"` or `"n"`. Adds [MkDocs](https://www.mkdocs.org/)
 documentation to your project. This includes automatically parsing
 your docstrings and adding them to the documentation. Documentation
 will be deployed to the `gh-pages` branch.

docs/tutorial.md

@@ -16,13 +16,13 @@ whenever you create them with `poetry init`.
 
 ## Step 2: Install pyenv (Optional)
 
-I would recommend to use `pyenv` for managing your different Python versions. However, if you prefer anohter method of
+I would recommend to use `pyenv` for managing your different Python versions. However, if you prefer another method of
 managing your Python versions, feel free to skip this step and continue to [step 3](#step-3-generate-your-project).  
 
 The instructions to install pyenv can be found [here](https://github.com/pyenv/pyenv). The instructions to install
 poetry can be found [here](https://python-poetry.org/docs/).
 
-Then, install a version of Python with pyenv. To see a list of available
+Install a version of Python with pyenv. To see a list of available
 versions, run:
 
 ``` bash
@@ -89,7 +89,13 @@ git push -u origin main
 
 ## Step 6: Activate your environment
 
-Install and activate the environment by running:
+If you are using `pyenv`, you might want to set the local `python` version to be used:
+
+```bash
+pyenv local x.y.z
+```
+
+Install and activate the `poetry` environment by running:
 
 ``` bash
 poetry install

hooks/post_gen_project.py

@@ -21,5 +21,5 @@ def remove_dir(filepath):
     if "{{cookiecutter.tox}}" != "y":
         remove_file("tox.ini")
 
-    if "{{cookiecutter.sphinx_docs}}" != "y":
+    if "{{cookiecutter.mkdocs}}" != "y":
         remove_dir("docs")

mkdocs.yml

@@ -13,7 +13,7 @@ nav:
     - Dependency management with Poetry: features/poetry.md
     - Publishing to PyPi or Artifactory: features/publishing.md
     - Testing with Pytest: features/pytest.md
-    - Documentation with Sphinx: features/sphinx.md
+    - Documentation with MkDocs: features/mkdocs.md
     - Compatibility testing with Tox: features/tox.md
   - Tutorial: tutorial.md
   - Prompt Arguments: prompt_arguments.md

pyproject.toml

@@ -19,17 +19,15 @@ include = [
 [tool.poetry.dependencies]
 python = ">=3.7,<4.0"
 cookiecutter = "^1.7.3"
-mkdocs = "^1.3.0"
-mkdocs-material = "^8.2.9"
 
 [tool.poetry.dev-dependencies]
 pytest = "^7.1.1"
 isort = "^5.10.1"
 black = "^22.3.0"
 pytest-cookies = "^0.6.1"
-Sphinx = "^4.5.0"
-sphinx-rtd-theme = "^1.0.0"
 tox = "^3.25.0"
+mkdocs = "^1.3.0"
+mkdocs-material = "^8.2.9"
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]