Skip to content

Commit 556f9a9

Browse files
coulingcouling
committed
Documentation
1 parent f14c335 commit 556f9a9

File tree

4 files changed

+25
-30
lines changed

4 files changed

+25
-30
lines changed

‎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
```

‎source/mkdocstrings_python_generator/plugin.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -88,9 +88,10 @@ def make_edit_url(self, config: MkDocsConfig, generated_file: GeneratedFileRef)
8888

8989
# Modify mkdocs config with overrides in this plugin's own configuration
9090
temp_config = config.copy()
91-
if self._config.edit_uri is not None:
91+
if self._config.edit_uri is not None or temp_config["edit_uri_template"] is not None:
92+
# These are supposed to be mutually exclusive, but it's possible the main mkdocs config specifies one
93+
# and the mkdocstings-python-generator specifies the other.
9294
temp_config["edit_uri"] = self._config.edit_uri
93-
if self._config.edit_uri_template is not None:
9495
temp_config["edit_uri_template"] = self._config.edit_uri_template
9596

9697
# Make a File object with the python source file as src_uri instead of the .md file

‎source/tests/test_files_generator.py‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,3 @@ def test_non_wildcard_ignore_is_discriminative(example_files: Path):
5454
results = {v.module_id for v in files_generator.discover_python_files(example_files, example_files, ["baz.py"])}
5555
assert "sub_package.baz" not in results
5656
assert "sub_package.baz_bob" in results
57-
58-
59-
def

0 commit comments

Comments
 (0)