10000 docs: Improve docs · laysauchoa/python@59c86df · GitHub
[go: up one dir, main page]
Skip to content

Commit 59c86df

Browse files
pawamoypawamoy
committed
docs: Improve docs
1 parent c15a10b commit 59c86df

File tree

4 files changed

+72
-66
lines changed

4 files changed

+72
-66
lines changed

‎docs/customization.md

Lines changed: 22 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -96,28 +96,28 @@ div.doc-contents:not(.first) {
9696

9797
Templates are organized into the following tree:
9898

99-
```
100-
📁 theme/
101-
├── 📄 attribute.html
102-
├── 📄 children.html
103-
├── 📄 class.html
104-
├── 📁 docstring/
105-
│   ├── 📄 admonition.html
106-
│   ├── 📄 attributes.html
107-
│   ├── 📄 examples.html
108-
│   ├── 📄 other_parameters.html
109-
│   ├── 📄 parameters.html
110-
│   ├── 📄 raises.html
111-
│   ├── 📄 receives.html
112-
│   ├── 📄 returns.html
113-
│   ├── 📄 warns.html
114-
│   └── 📄 yields.html
115-
├── 📄 docstring.html
116-
├── 📄 expression.html
117-
├── 📄 function.html
118-
├── 📄 labels.html
119-
├── 📄 module.html
120-
└── 📄 signature.html
99+
```tree result="text"
100+
theme/
101+
attribute.html
102+
children.html
103+
class.html
104+
docstring/
105+
admonition.html
106+
attributes.html
107+
examples.html
108+
other_parameters.html
109+
parameters.html
110+
raises.html
111+
receives.html
112+
returns.html
113+
warns.html
114+
yields.html
115+
docstring.html
116+
expression.html
117+
function.html
118+
labels.html
119+
module.html
120+
signature.html
121121
```
122122

123123
See them [in the repository](https://github.com/mkdocstrings/python/tree/master/src/mkdocstrings_handlers/python/templates/).

‎docs/usage.md

Lines changed: 42 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Usage
22

3-
WARNING: **This is the documentation for the NEW, EXPERIMENTAL Python handler.**
3+
TIP: **This is the documentation for the NEW Python handler.**
44
To read the documentation for the LEGACY handler,
55
go to the [legacy handler documentation](https://mkdocstrings.github.io/python-legacy).
66

@@ -17,7 +17,7 @@ Like every handler, the Python handler accepts both **global** and **local** opt
1717

1818
Some options are **global only**, and go directly under the handler's name.
1919

20-
- `import`: This option is used to import Sphinx-compatible objects inventories from other
20+
- `import`: this option is used to import Sphinx-compatible objects inventories from other
2121
documentation sites. For example, you can import the standard library
2222
objects inventory like this:
2323

@@ -138,10 +138,10 @@ so that the current working directory has no impact on the build process:
138138
TIP: **This is the recommended method.**
139139

140140
1. mkdocs.yml in root, package in root
141-
```
142-
📁 root/
143-
├── 📄 mkdocs.yml
144-
└── 📁 package/
141+
```tree
142+
root/
143+
mkdocs.yml
144+
package/
145145
```
146146

147147
```yaml title="mkdocs.yml"
@@ -153,11 +153,11 @@ TIP: **This is the recommended method.**
153153
```
154154

155155
1. mkdocs.yml in root, package in subfolder
156-
```
157-
📁 root/
158-
├── 📄 mkdocs.yml
159-
└── 📁 src/
160-
└── 📁 package/
156+
```tree
157+
root/
158+
mkdocs.yml
159+
src/
160+
341A package/
161161
```
162162

163163
```yaml title="mkdocs.yml"
@@ -169,11 +169,11 @@ TIP: **This is the recommended method.**
169169
```
170170

171171
1. mkdocs.yml in subfolder, package in root
172-
```
173-
📁 root/
174-
├── 📁 docs/
175-
│ └── 📄 mkdocs.yml
176-
└── 📁 package/
172+
```tree
173+
root/
174+
docs/
175+
mkdocs.yml
176+
package/
177177
```
178178

179179
```yaml title="mkdocs.yml"
@@ -185,12 +185,12 @@ TIP: **This is the recommended method.**
185185
```
186186

187187
1. mkdocs.yml in subfolder, package in subfolder
188-
```
189-
📁 root/
190-
├── 📁 docs/
191-
│ └── 📄 mkdocs.yml
192-
└── 📁 src/
193-
└── 📁 package/
188+
```tree
189+
root/
190+
docs/
191+
mkdocs.yml
192+
src/
193+
package/
194194
```
195195

196196
```yaml title="mkdocs.yml"
@@ -218,47 +218,47 @@ In Bash and other shells, you can run your command like this
218218
(note the prepended `PYTHONPATH=...`):
219219

220220
1. mkdocs.yml in root, package in root
221-
```
222-
📁 root/
223-
├── 📄 mkdocs.yml
224-
└── 📁 package/
221+
```tree
222+
root/
223+
mkdocs.yml
224+
package/
225225
```
226226

227227
```bash
228228
PYTHONPATH=. mkdocs build # actually not needed, default
229229
```
230230

231231
1. mkdocs.yml in root, package in subfolder
232-
```
233-
📁 root/
234-
├── 📄 mkdocs.yml
235-
└── 📁 src/
236-
└── 📁 package/
232+
```tree
233+
root/
234+
mkdocs.yml
235+
src/
236+
package/
237237
```
238238

239239
```bash
240240
PYTHONPATH=src mkdocs build
241241
```
242242

243243
1. mkdocs.yml in subfolder, package in root
244-
```
245-
📁 root/
246-
├── 📁 docs/
247-
│ └── 📄 mkdocs.yml
248-
└── 📁 package/
244+
```tree
245+
root/
246+
docs/
247+
mkdocs.yml
248+
package/
249249
```
250250

251251
```bash
252252
PYTHONPATH=. mkdocs build -f docs/mkdocs.yml
253253
```
254254

255255
1. mkdocs.yml in subfolder, package in subfolder
256-
```
257-
📁 root/
258-
├── 📁 docs/
259-
│ └── 📄 mkdocs.yml
260-
└── 📁 src/
261-
└── 📁 package/
256+
```tree
257+
root/
258+
docs/
259+
mkdocs.yml
260+
src/
261+
package/
262262
```
263263

264264
```bash

‎scripts/gen_credits.py

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
import re
2-
from importlib.metadata import metadata, PackageNotFoundError
32
from itertools import chain
43
from pathlib import Path
54
from textwrap import dedent
@@ -8,6 +7,11 @@
87
from jinja2 import StrictUndefined
98
from jinja2.sandbox import SandboxedEnvironment
109

10+
try:
11+
from importlib.metadata import metadata, PackageNotFoundError
12+
except ImportError:
13+
from importlib_metadata import metadata, PackageNotFoundError
14+
1115
project_dir = Path(".")
1216
pyproject = toml.load(project_dir / "pyproject.toml")
1317
project = pyproject["project"]

‎src/mkdocstrings_handlers/python/handler.py

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,9 @@ class PythonHandler(BaseHandler):
8888
members_order (str): The members ordering to use. Options: `alphabetical` - order by the members names,
8989
`source` - order members as they appear in the source file. Default: `"alphabetical"`.
9090
filters (list[str] | None): A list of filters applied to filter objects based on their name.
91-
A filter starting with `!` will exclude matching objects instead of including them. Default: `["!^_[^_]"]`.
91+
A filter starting with `!` will exclude matching objects instead of including them.
92+
The `members` option takes precedence over `filters` (filters will still be applied recursively
93+
to lower members in the hierarchy). Default: `["!^_[^_]"]`.
9294
group_by_category (bool): Group the object's children by categories: attributes, classes, functions, and modules. Default: `True`.
9395
show_submodules (bool): When rendering a module, show its submodules recursively. Default: `False`.
9496

0 commit comments

Comments
 (0)
0