Skip to content

Commit

Permalink
fix img path to ../img/
Browse files Browse the repository at this point in the history
  • Loading branch information
chendaniely committed Jan 20, 2025
1 parent 8c739ba commit 2cfa3e5
Showing 1 changed file with 8 additions and 8 deletions.
16 changes: 8 additions & 8 deletions book/lectures/205-package_documentation_python.qmd
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down Expand Up @@ -65,7 +65,7 @@ that are needed for this to work.
-------
bool
Description of return value
Examples
--------
>>> my_funtion(4)
Expand All @@ -82,23 +82,23 @@ 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):

<img src="img/index-raw.png" width=300>
<img src="../img/index-raw.png" width=300>

This results in a side bar on our webpage that looks like this:

<img src="img/original-index.png" width=700>
<img src="../img/original-index.png" width=700>

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.

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:

<img src="img/index-raw-headers.png" width=300>
<img src="../img/index-raw-headers.png" width=300>

Which will result in this rendering:

<img src="img/rendered-index-headers.png" width=1000>
<img src="../img/rendered-index-headers.png" width=1000>


## Vignettes/tutorials
Expand Down Expand Up @@ -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: <https://sphinx-themes.org/>
Expand Down

0 comments on commit 2cfa3e5

Please sign in to comment.