-
Notifications
You must be signed in to change notification settings - Fork 61
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Move from Sphinx to MkDocs for the cookiecutter package (#31)
- Loading branch information
Florian Maas
authored
Apr 16, 2022
1 parent
cc6d075
commit 947c7a8
Showing
35 changed files
with
209 additions
and
253 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Empty file.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.