You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+6-7Lines changed: 6 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,21 +2,20 @@
2
2
3
3
> [!NOTE]
4
4
> **In early development!**
5
-
> Expect bugs, missing features, and incomplete documentation.
6
-
> Docstub is still evaluating which features it needs to support as the community gives feedback.
7
-
> Several features are experimental and included to make adoption of docstub easier.
8
-
> Long-term, some of these might be discouraged or removed as docstub matures.
5
+
> Docstub is not feature-complete or thoroughly tested yet.
6
+
> Its behavior, configuration or command line interface may change significantly between releases.
9
7
10
-
docstub is a command-line tool to generate [Python stub files](https://typing.python.org/en/latest/guides/writing_stubs.html) (i.e., PYI files) from type descriptions found in [numpydoc](https://numpydoc.readthedocs.io)-style docstrings.
8
+
docstub is a command-line tool to generate [Python stub files](https://typing.python.org/en/latest/guides/writing_stubs.html).
9
+
It extracts necessary type information from [NumPyDoc style](https://numpydoc.readthedocs.io) docstrings.
11
10
12
11
Many packages in the scientific Python ecosystem already describe expected parameter and return types in their docstrings.
13
12
Docstub aims to take advantage of these and help with the adoption of type annotations.
14
-
It does so by supporting widely used readable conventions such as `array of dtype` or `iterable of int(s)` which it translates into valid type annotations.
13
+
It does so by supporting widely used readable conventions such as `array of dtype` or `iterable of int(s)` which are translated into valid type annotations.
15
14
16
15
17
16
## Installation & getting started
18
17
19
-
Please refer to the [user guide](https://github.com/scientific-python/docstub/blob/main/docs/user_guide.md) to get started with docstub.
18
+
Please refer to the installation guide and introduction in our [official documentation](https://docstub.readthedocs.io/) or in [docs/](docs/) to get started.
The reference for docstub's command line interface.
4
+
It uses [Click](https://click.palletsprojects.com/en/stable/), so [shell completion](https://click.palletsprojects.com/en/stable/shell-completion/) can be enabled.
5
+
6
+
Colored command line output can be disabled by [setting the environment variable `NO_COLOR=1`](https://no-color.org).
7
+
8
+
9
+
## `docstub`
4
10
5
11
<!--- The following block is checked by the test suite --->
6
12
<!--- begin cli-docstub --->
7
13
8
-
```plain
14
+
```none
9
15
Usage: docstub [OPTIONS] COMMAND [ARGS]...
10
16
11
17
Generate Python stub files from docstrings.
12
18
13
19
Options:
14
-
--version Show the version and exit.
15
-
-h, --help Show this message and exit.
20
+
--version
21
+
Show the version and exit.
22
+
-h, --help
23
+
Show this message and exit.
16
24
17
25
Commands:
18
26
clean Clean the cache.
@@ -22,51 +30,67 @@ Commands:
22
30
<!--- end cli-docstub --->
23
31
24
32
25
-
## Command `docstub run`
33
+
## `docstub run`
26
34
27
35
<!--- The following block is checked by the test suite --->
28
36
<!--- begin cli-docstub-run --->
29
37
30
-
```plain
38
+
```none
31
39
Usage: docstub run [OPTIONS] PACKAGE_PATH
32
40
33
41
Generate Python stub files.
34
42
35
-
Given a `PACKAGE_PATH` to a Python package, generate stub files for it. Type
43
+
Given a PACKAGE_PATH to a Python package, generate stub files for it. Type
36
44
descriptions in docstrings will be used to fill in missing inline type
37
45
annotations or to override them.
38
46
39
47
Options:
40
-
-o, --out-dir PATH Set output directory explicitly. Stubs will be directly
41
-
written into that directory while preserving the
42
-
directory structure under `PACKAGE_PATH`. Otherwise,
43
-
stubs are generated inplace.
44
-
--config PATH Set one or more configuration file(s) explicitly.
45
-
Otherwise, it will look for a `pyproject.toml` or
46
-
`docstub.toml` in the current directory.
47
-
--ignore GLOB Ignore files matching this glob-style pattern. Can be
48
-
used multiple times.
49
-
--group-errors Group identical errors together and list where they
50
-
occurred. Will delay showing errors until all files have
51
-
been processed. Otherwise, simply report errors as the
52
-
occur.
53
-
--allow-errors INT Allow this many or fewer errors. If docstub reports
54
-
more, exit with error code '1'. This is useful to adopt
55
-
docstub gradually. [default: 0; x>=0]
56
-
--no-cache Ignore pre-existing cache and don't create a new one.
57
-
-v, --verbose Print more details (repeatable).
58
-
-h, --help Show this message and exit.
48
+
-o, --out-dir PATH
49
+
Set output directory explicitly. Stubs will be directly written into
50
+
that directory while preserving the directory structure under
51
+
PACKAGE_PATH. Otherwise, stubs are generated inplace.
52
+
--ignore GLOB
53
+
Ignore files matching this glob-style pattern. Can be used multiple
54
+
times.
55
+
-g, --group-errors
56
+
Group identical errors together and list where they occurred. Will
57
+
delay showing errors until all files have been processed. Otherwise,
58
+
simply report errors as the occur.
59
+
--allow-errors INT
60
+
Allow this many or fewer errors. If docstub reports more, exit with
61
+
error code 1. This is useful to adopt docstub gradually. [default:
62
+
0; x>=0]
63
+
-W, --fail-on-warning
64
+
Return non-zero exit code when a warning is raised. Will add to
65
+
--allow-errors.
66
+
--workers INT
67
+
Experimental: Process files in parallel with the desired number of
68
+
workers. By default, no multiprocessing is used. [default: 1]
69
+
--no-cache
70
+
Ignore pre-existing cache and don't create a new one.
71
+
--config PATH
72
+
Set one or more configuration file(s) explicitly. Otherwise, it will
73
+
look for a `pyproject.toml` or `docstub.toml` in the current
74
+
directory.
75
+
-v, --verbose
76
+
Print more details. Use once to show information messages. Use -vv to
77
+
print debug messages.
78
+
-q, --quiet
79
+
Print less details. Use once to hide warnings. Use -qq to completely
80
+
silence output.
81
+
-h, --help
82
+
Show this message and exit.
59
83
```
60
84
61
85
<!--- end cli-docstub-run --->
62
86
63
87
64
-
## Command `docstub clean`
88
+
## `docstub clean`
65
89
66
90
<!--- The following block is checked by the test suite --->
67
91
<!--- begin cli-docstub-clean --->
68
92
69
-
```plain
93
+
```none
70
94
Usage: docstub clean [OPTIONS]
71
95
72
96
Clean the cache.
@@ -75,8 +99,14 @@ Usage: docstub clean [OPTIONS]
75
99
one exists, remove it.
76
100
77
101
Options:
78
-
-v, --verbose Print more details (repeatable).
79
-
-h, --help Show this message and exit.
102
+
-v, --verbose
103
+
Print more details. Use once to show information messages. Use -vv to
104
+
print debug messages.
105
+
-q, --quiet
106
+
Print less details. Use once to hide warnings. Use -qq to completely
0 commit comments