Mkdocs (#30)

* converted docs to mkdocs

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

@@ -24,7 +24,7 @@ jobs:
       - name: Documentation Test
         run: |
           source .venv/bin/activate
-          make docs-test
+          make docs-verify
 
   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-test
+          make docs-verify
 
   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-test
+          make docs-verify
 
   tox:
     runs-on: ubuntu-latest
@@ -83,10 +83,4 @@ jobs:
       - name: Generate documentation
         run: |
             source .venv/bin/activate
-            make docs-build
-
-      - name: Deploy documentation to GitHub pages
-        uses: peaceiris/actions-gh-pages@v3
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs/_build
+            mkdocs gh-deploy

Makefile

@@ -41,19 +41,11 @@ publish: ## publish a release to pypi.
 
 build-and-publish: build publish ## Build and publish.
 
-docs-test: ## Test Sphinx documentation.
-	@sphinx-build docs docs/_build -W --keep-going
+docs-verify: ## Check if MkDocs build does not return warnings or errors
+	@mkdocs build -s
 
-docs-clean: ## Clean the docs/_build folder 
-	@rm -rf docs/_build/*
-
-docs-build: ## Build the documentation
-	@sphinx-build docs docs/_build
-
-docs-open: ## Open the documentation
-	@open docs/_build/index.html
-
-docs: docs-clean docs-build docs-open ## Build and open the documentation
+docs-serve: ## Build and serve the MkDocs documentation
+	@mkdocs serve
 
 .PHONY: help
 

README.rst

@@ -36,8 +36,6 @@ 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.
 
-+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
-| **Github repository**         | `https://github.com/fpgmaas/cookiecutter-poetry/ <https://github.com/fpgmaas/cookiecutter-poetry/>`_                                 |
 +-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
 | **Documentation**             | `https://fpgmaas.github.io/cookiecutter-poetry/ <https://fpgmaas.github.io/cookiecutter-poetry/>`_                                   |
 +-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+

docs/features/cicd.md

@@ -0,0 +1,41 @@
+---
+title: CI/CD with Github actions
+---
+
+when `include_github_actions` is set to `"y"`, a `.github` directory is
+added with the following structure:
+
+    .github
+    ├── workflows
+    ├─── run-checks
+    │    └── action.yml    
+    ├─── setup-poetry-env
+    │    └── action.yml         
+    ├── on-merge-to-main.yml
+    ├── on-pull-request.yml          
+    └── on-release-main.yml
+
+`on-merge-to-main.yml` and `on-pull-request.yml` are identical except
+for their trigger conditions; the first is run whenever a new commit is
+made to `main` (which should
+[only](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches)
+happen through merge requests, hence the name), and the latter is run
+whenever a pull request is opened or updated. They call the `action.yml`
+files to set-up the environment, run the tests, and check the code
+formatting.
+
+`on-release-main.yml` does all of the former whenever a new release is
+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"}
+
+Additionally, all workflows check for compatibility with multiple Python
+versions if `tox` is set to `"y"`.
+
+## 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/formatting.md

@@ -0,0 +1,20 @@
+---
+title: Formatting
+---
+
+[isort](https://pycqa.github.io/isort/index.html) and
+[black](https://pypi.org/project/black/) are added as development
+dependencies. `black` and `isort` can be used to format the code with
+
+``` bash
+make format
+```
+
+And the code style can be checked with
+
+``` bash
+make lint
+```
+
+If `include_github_actions` is set to `"y"`, code formatting is checked
+for every merge request, every merge to main, and every release.

docs/features/makefile.md

@@ -0,0 +1,25 @@
+---
+title: Makefile
+---
+
+The generated repository will have a `Makefile` available. A list of all
+available commands that are available can be obtained by running
+`make help` in the terminal. Initially, the following commands are
+available:
+
+```
+install              Install the poetry environment
+format               Format code using isort and black.
+lint                 Check code formatting using isort and black.
+test                 Test the code with pytest
+build                Build wheel file using poetry
+clean-build          clean build artifacts
+publish              publish a release to pypi.
+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-test            Test if the documentation can be generated and built without errors.
+```

docs/features/poetry.md

@@ -0,0 +1,23 @@
+---
+title: Poetry
+---
+
+The generated repository will uses [Poetry](https://python-Poetry.org/)
+for its dependency management. When you have created your repository
+using this cookiecutter template, a Poetry environment is pre-configured
+in `pyproject.toml` and `Poetry.toml`. All you need to do is add your
+project-specific dependencies with
+
+``` bash
+poetry add <package>
+```
+
+and then install the environment with
+
+``` bash
+make install
+```
+
+By default, the environment is created in a `.venv` folder, so you can
+easily start an interactive shell within the environment with
+`poetry shell`.