diff --git a/book/lectures/205-package_documentation_python.qmd b/book/lectures/205-package_documentation_python.qmd index 3b954fe..9922690 100644 --- a/book/lectures/205-package_documentation_python.qmd +++ b/book/lectures/205-package_documentation_python.qmd @@ -10,9 +10,9 @@ title: "Package Documentation: Python" In Python, we use formatted docstrings to generate our code-level documentation. We then use a tool called [`sphinx`](https://www.sphinx-doc.org/en/master/index.html) -to take those formatted docstrings to generate our API reference documentation +to take those formatted docstrings to generate our API reference documentation for our package website, and several of our Markdown files in our packages -GitHub repository to generate other pages for our package website +GitHub repository to generate other pages for our package website (Contributing, Code of Conduct, etc). We then serve the website up on some platform, such as [Read the Docs](https://readthedocs.org/) (others exist as well). @@ -65,7 +65,7 @@ that are needed for this to work. ------- bool Description of return value - + Examples -------- >>> my_funtion(4) @@ -82,11 +82,11 @@ How do we add new pages to our Python package-level documentation? The pages tha Let's take a look at the [raw version of that file from our `pypkgs-cookiecutter`](https://raw.githubusercontent.com/py-pkgs/py-pkgs-cookiecutter/main/%7B%7B%20cookiecutter.__package_slug%20%7D%7D/docs/index.md): - + This results in a side bar on our webpage that looks like this: - + Thus, to add new pages, we add them to the `toctree` list. They will then show up in that position in the rendered side bar. @@ -94,11 +94,11 @@ What if we want headers in our side bar? To do this, we need to add multiple `toctree`'s and add a caption. Here's an example: - + Which will result in this rendering: - + ## Vignettes/tutorials @@ -160,7 +160,7 @@ sphinx: ### Sphinx themes Sometimes you want to have a different theme for your project's docs. -This is possible by changing `html_theme` in `doc.conf.py`. +This is possible by changing `html_theme` in `doc.conf.py`. See the link below to view and read the docs for other Sphinx themes: - Sphinx themes gallery: