Skip to content

Refactor and cleanup #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
couling merged 6 commits into from
Nov 5, 2024
Merged

Refactor and cleanup #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
3be9864
Refactor and cleanup
couling Nov 4, 2024
a300568
lock
couling Nov 4, 2024
c37e6d7
Unit test fix
couling Nov 4, 2024
f14c335
Added unit tests
couling Nov 5, 2024
556f9a9
Documentation
couling Nov 5, 2024
06c6632
Mypy fix
couling Nov 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,5 +47,4 @@ python3 -m build <project dir>
poetry self add poetry-dynamic-versioning
cd <project dir>
poetry build

```
42 changes: 20 additions & 22 deletions mkdocs/docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,18 +7,17 @@ For mkdocstrings-python configuration: [see here](https://mkdocstrings.github.io
```yaml

- mkdocstrings-python-generator:
nav_heading:
- Code Reference
search:
- src/my_package
base: src
ignore:
- test_*


edit_uri: edit/main/src/
init_section_index: true
prune_nav_prefix: my_package
source_dirs:
- nav_heading: ["Code Reference"]
package_dir: src/my_namespace/my_package
base: src
ignore:
- test_*
edit_uri: edit/main/src/
# edit_uri_template: edit/main/src/{path}
hide_namespace: my_namespace

- ...

# This part of the config is up to you.
- mkdocstrings:
Expand All @@ -29,13 +28,12 @@ For mkdocstrings-python configuration: [see here](https://mkdocstrings.github.io

## Options

| Option Name | Description | Value Type |
|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|
| `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 |
| `search` | Search paths to look for python files relative to mkdocs.yaml | List of Strings |
| `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 |
| `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 |
| `edit_uri` | Override mkdocs [edit_uri](https://www.mkdocs.org/user-guide/configuration/#edit_uri) for generated files | String |
| `edit_uri_template` | Override mkdocs [edit_uri_template](https://www.mkdocs.org/user-guide/configuration/#edit_uri_template) for generated files | String |
| `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 |
| `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 |
| Option Name | Description | Value Type |
|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|
| `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 |
| `base` | The source directory of your project relative to the mkdocs configuration yaml file | String |
| `package_dir` | Normally `base` is enough, `package_dir` lets you specify exactly which package inside `base` to document. | Sting |
| `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 |
| `edit_uri` | Override mkdocs [edit_uri](https://www.mkdocs.org/user-guide/configuration/#edit_uri) for generated files | String |
| `edit_uri_template` | Override mkdocs [edit_uri_template](https://www.mkdocs.org/user-guide/configuration/#edit_uri_template) for generated files | String |
| `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 |
5 changes: 2 additions & 3 deletions mkdocs/docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,7 @@ See [Configuration](../configuration/) for more detail

# Configure mkdocstrings-python-generator
- mkdocstrings-python-generator:
search:
source_dirs:
# Path to your source directory relative to mkdocs.yaml directory.
- src/

- base: src/
```
15 changes: 7 additions & 8 deletions mkdocs/mkdocs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ nav:
- Welcome: index.md
- Configuration: configuration.md


# Enable the theme "Material"
theme:
name: "material"
Expand Down Expand Up @@ -49,15 +50,13 @@ plugins:
show_submodules: false
selection:
docstring_style: sphinx

- mkdocstrings-python-generator:
nav_heading:
- Code Reference
base: ../source
edit_uri: edit/main/source/
init_section_index: true
search:
- ../source/mkdocstrings_python_generator
prune_nav_prefix: mkdocstrings_python_generator
source_dirs:
- nav_heading:
- Code Reference
base: ../source/
edit_uri: edit/main/source/

watch:
- docs
Expand Down
Loading