Skip to content

Commit e985469

Browse files
coulingcouling
authored
Refactor and cleanup (#2)
1 parent d412efc commit e985469

File tree

21 files changed

+1040
-773
lines changed

21 files changed

+1040
-773
lines changed

‎README.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,5 +47,4 @@ python3 -m build <project dir>
4747
poetry self add poetry-dynamic-versioning
4848
cd <project dir>
4949
poetry build
50-
5150
```

‎mkdocs/docs/configuration.md‎

Lines changed: 20 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -7,18 +7,17 @@ For mkdocstrings-python configuration: [see here](https://mkdocstrings.github.io
77
```yaml
88

99
- mkdocstrings-python-generator:
10-
nav_heading:
11-
- Code Reference
12-
search:
13-
- src/my_package
14-
base: src
15-
ignore:
16-
- test_*
17-
18-
19-
edit_uri: edit/main/src/
20-
init_section_index: true
21-
prune_nav_prefix: my_package
10+
source_dirs:
11+
- nav_heading: ["Code Reference"]
12+
package_dir: src/my_namespace/my_package
13+
base: src
14+
ignore:
15+
- test_*
16+
edit_uri: edit/main/src/
17+
# edit_uri_template: edit/main/src/{path}
18+
hide_namespace: my_namespace
19+
20+
- ...
2221

2322
# This part of the config is up to you.
2423
- mkdocstrings:
@@ -29,13 +28,12 @@ For mkdocstrings-python configuration: [see here](https://mkdocstrings.github.io
2928
3029
## Options
3130
32-
| Option Name | Description | Value Type |
33-
|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|
34-
| `nav_heading` | Describes where to place the generated files on the nav. Eg: if you want `Reference` > `Code Reference` then set `["Reference", "Code Reference"]` | List of Strings |
35-
| `search` | Search paths to look for python files relative to mkdocs.yaml | List of Strings |
36-
| `base` | If different from the search paths, set this to the base directory of python files similar to might be added as `PYTHONPATH`. ⚠️ Only one base may be specified | String |
37-
| `ignore` | List of [glob expressions](https://docs.python.org/3/library/glob.html#glob.glob) to ignore from the search. These are applied per file and so cannot specify directories. | List of Strings |
38-
| `edit_uri` | Override mkdocs [edit_uri](https://www.mkdocs.org/user-guide/configuration/#edit_uri) for generated files | String |
39-
| `edit_uri_template` | Override mkdocs [edit_uri_template](https://www.mkdocs.org/user-guide/configuration/#edit_uri_template) for generated files | String |
40-
| `init_section_index` | Some themes such as Material support [section indexes](https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#section-index-pages). If enabled `__init__.py` files with content will be used to define section index pages | Boolean |
41-
| `prune_nav_prefix` | If your package exists deep in some namespace you can remove specific parents from the nav keeping the nav cleaner and simpler. Simply name the python prefix you want to prune from the nav. Eg: `foo.bar.my_namespace_package` | String |
31+
| Option Name | Description | Value Type |
32+
|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|
33+
| `nav_heading` | Describes where to place the generated files on the nav. Eg: if you want `Reference` > `Code Reference` then set `["Reference", "Code Reference"]` | List of Strings |
34+
| `base` | The source directory of your project relative to the mkdocs configuration yaml file | String |
35+
| `package_dir` | Normally `base` is enough, `package_dir` lets you specify exactly which package inside `base` to document. | Sting |
36+
| `ignore` | List of [glob expressions](https://docs.python.org/3/library/glob.html#glob.glob) to ignore from the search. These are applied per file and so cannot specify directories. Default [`test`, `tests`, `__main__.py`]. | List of Strings |
37+
| `edit_uri` | Override mkdocs [edit_uri](https://www.mkdocs.org/user-guide/configuration/#edit_uri) for generated files | String |
38+
| `edit_uri_template` | Override mkdocs [edit_uri_template](https://www.mkdocs.org/user-guide/configuration/#edit_uri_template) for generated files | String |
39+
| `hide_namespace` | When using [namespace packages](https://packaging.python.org/en/latest/guides/packaging-namespace-packages/), it is sometimes unhelpful to have the namespace appear as a level on the nav bar. This option lets you move a namespace's packages up a level and so hide the naspace on the nav. Simply name the python prefix you want to prune from the nav. Eg: if your package is `foo.bar.my_package` and `foo` is the namespace. Set `hide_namespace: foo` and the nav will then just be `bar` -> `my_package`. | String |

‎mkdocs/docs/index.md‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,8 +34,7 @@ See [Configuration](../configuration/) for more detail
3434

3535
# Configure mkdocstrings-python-generator
3636
- mkdocstrings-python-generator:
37-
search:
37+
source_dirs:
3838
# Path to your source directory relative to mkdocs.yaml directory.
39-
- src/
40-
39+
- base: src/
4140
```

‎mkdocs/mkdocs.yaml‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ nav:
1010
- Welcome: index.md
1111
- Configuration: configuration.md
1212

13+
1314
# Enable the theme "Material"
1415
theme:
1516
name: "material"
@@ -49,15 +50,13 @@ plugins:
4950
show_submodules: false
5051
selection:
5152
docstring_style: sphinx
53+
5254
- mkdocstrings-python-generator:
53-
nav_heading:
54-
- Code Reference
55-
base: ../source
56-
edit_uri: edit/main/source/
57-
init_section_index: true
58-
search:
59-
- ../source/mkdocstrings_python_generator
60-
prune_nav_prefix: mkdocstrings_python_generator
55+
source_dirs:
56+
- nav_heading:
57+
- Code Reference
58+
base: ../source/
59+
edit_uri: edit/main/source/
6160

6261
watch:
6362
- docs

0 commit comments

Comments
 (0)