Skip to content

Commit f13d271

Browse files
committed
Fix: use auto-api
1 parent fdae3df commit f13d271

File tree

5 files changed

+50
-4
lines changed

5 files changed

+50
-4
lines changed

docs/conf.py

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,10 @@
3636
# Extensions add additional functionality to your documentation.
3737
# TODO: describe each extension below
3838
extensions = [
39+
# Autodoc will create API docs for you
40+
# "sphinx.ext.autodoc", # This is the older autodoc that doesn't support myst
41+
"autodoc2", # Supports myst markdown, ugly output
42+
"autoapi.extension",
3943
"sphinx_design",
4044
"sphinx_copybutton",
4145
"sphinx.ext.intersphinx",
@@ -64,3 +68,11 @@
6468

6569
html_theme = "pydata_sphinx_theme"
6670
html_static_path = ["_static"]
71+
72+
# Autodoc
73+
# autodoc2_render_plugin = "myst"
74+
# autodoc2_packages = [
75+
# "../src/pyospackage",
76+
# ]
77+
78+
autoapi_dirs = ["../src/pyospackage"]

docs/documentation/setup-sphinx.md

Lines changed: 20 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,14 +19,14 @@ Below is the Sphinx-quickstart workflow used to create these docs. However,
1919
inevitably you will likely customize the documentation setup. So you may also
2020
want to just copy this repository's structure.
2121

22-
```
22+
```bash
2323
➜ sphinx-quickstart
2424
Welcome to the Sphinx 5.3.0 quickstart utility.
2525

2626
Please enter values for the following settings (just press Enter to
2727
accept a default value, if one is given in brackets).
2828

29-
Selected root path: .
29+
Selected root path: docs
3030

3131
You have two options for placing the build directory for Sphinx output.
3232
Either, you use a directory "_build" within the root path, or you separate
@@ -47,5 +47,21 @@ https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
4747
> Project language [en]: en
4848
```
4949
50-
The `conf.py` file is the core that you use to configure your sphinx docs.
51-
The conf.py file in this package is setup
50+
## About the conf.py file
51+
52+
The `conf.py` file is what Sphinx uses to configure your documentation. This is
53+
where you setup all of the features that you want your documentation to have.
54+
55+
:::{note}
56+
Every tool and theme that you might use will have different configuration options
57+
that will be placed in the `conf.py` file.
58+
:::
59+
60+
## API / Reference documentation
61+
62+
It's useful to have a reference section in your docs that contains documentation
63+
for your package's methods and classes. In this demo package we are using
64+
autodoc2 which will create these reference docs for you automatically.
65+
66+
We like `autodoc2` over `sphinx_autodoc` extension because it supports `myst`
67+
markdown.

docs/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
home <self>
88
hatch scripts <hatch-envs-scripts>
99
Setup Sphinx <documentation/setup-sphinx>
10+
Reference / API <apidocs/index>
1011
:::
1112

1213
:::{toctree}

pyproject.toml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,9 @@ dependencies = [
4242
"sphinx-copybutton",
4343
"myst-nb",
4444
"myst-parser",
45+
"sphinx-autoapi",
46+
# Autodoc2 supports myst mardown
47+
#"sphinx-autodoc2"
4548
]
4649

4750

src/pyospackage/add_numbers.py

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,18 @@ def add_num(
55
a: int,
66
b: int,
77
) -> int:
8+
"""A function that adds two numbers together
9+
10+
Parameters
11+
----------
12+
a : int
13+
The first integer to be added.
14+
b : int
15+
The second integer to be added.
16+
17+
Returns
18+
-------
19+
int
20+
The sum of the two provided integers.
21+
"""
822
return a + b

0 commit comments

Comments
 (0)