https://github.com/baggepinnen/automaticdocstrings.jl
Automatically generated docstring stubs
https://github.com/baggepinnen/automaticdocstrings.jl
documentation documentation-generator productivity-booster
Last synced: about 1 month ago
JSON representation
Automatically generated docstring stubs
- Host: GitHub
- URL: https://github.com/baggepinnen/automaticdocstrings.jl
- Owner: baggepinnen
- License: mit
- Created: 2019-05-24T07:55:21.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-07-20T05:59:12.000Z (about 2 years ago)
- Last Synced: 2025-08-19T03:20:22.398Z (about 2 months ago)
- Topics: documentation, documentation-generator, productivity-booster
- Language: Julia
- Size: 40 KB
- Stars: 29
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# AutomaticDocstrings
[](https://github.com/baggepinnen/AutomaticDocstrings.jl/actions)
[](https://codecov.io/gh/baggepinnen/AutomaticDocstrings.jl)
This small package automatically generates docstring stubs for you to fill in.
Install using `import Pkg; Pkg.add("AutomaticDocstrings")`
# Usage
Place the macro call `@autodoc` above the function or struct definition that you want to generate a docstring for:
```julia
using AutomaticDocstrings
@autodoc
function f(x::A, b=5; c=LinRange(1,2,10)) where A
5
end
```
When you execute the macro, e.g. by ctrl-enter in Juno, the macro is replaced by a docstring
```julia
"""
f(x::A, b=5; c=LinRange(1,2,10))
DOCSTRING
# Arguments:
- `x`: DESCRIPTION
- `b`: DESCRIPTION
- `c`: DESCRIPTION
"""
function f(x::A, b=5; c=LinRange(1,2,10)) where A
5
end
```
Before modifying your file, a backup is saved.
```julia-repl
[ Info: Saved a backup to /tmp/jl_VQvgbW/backup
```
If you don't like the docstring or if something went wrong, ctrl-z (undo) works fine as well.
# Limitations
- If a file with multiple `@autodoc` are `include`ed, then only the first will be executed and then an error is thrown. Instead of `include(file)` call `autodoc(file)`.
- Make sure the file is saved before you try to generate any docstrings.
# VS code snippet
Adding the following snippet to vscode makes it easy to insert an automatically generated docstring, just make sure to save the file before executing the `@autodoc` macro.
```json
"autodoc": {
"prefix": "autodoc",
"body": ["${1:@eval Main using AutomaticDocstrings}$2\n@eval Main @autodoc"],
},
```
# Options
You may modify the `AutomaticDocstrings.options::Dict` to change some default values:
- `:min_args = 3`: Minimum number of arguments to print the argument list of function
- `:args_header = "# Arguments:"`: Printed above the argument list of function
- `:kwargs_header = nothing`: Printed above the keyword argument list of function
- `:struct_fields_header = "# Fields:"`: Printed above the fields list of a struct
- `:arg_types_in_desc = false`: Include the argument types in the description
- `:defaults_in_desc = false`: Include the default values in the description
- `:arg_types_in_header = false`: Include the argument types in the function header
- `:defaults_in_header = false`: Include the default values in the function header
-
You can always call `restore_defaults()` to restore the default options.