Simplify the guide and focus on iterative package / docs development #1451
Conversation
haampie
force-pushed
the
master
branch
5 times, most recently
from
75920cb
to
4be48f3
Compare
|
This new guide is a bit sneaky, in the sense that Revise.jl only seems to pick up new docstrings when the newly created Example package contains at least one function with a docstring from the start. So instead of starting with 0 docstrings like in the original guide, a first step is to add a docstring to the |
There was a problem hiding this comment.
Thanks a lot @haampie! This is great -- this page really needs some updating. And sorry for a delayed review.
I wonder if it would be good to have a really quickstart section for a user who needs to edit the documentation of an existing package (so omit the setup, just focus on calling Documenter)?
|
|
||
| ## Preliminaries | ||
|
|
There was a problem hiding this comment.
I would add a paragraph here about why you'd want to use this more interactive workflow. E.g. something along these lines (but edits definitely welcome):
| While the standard Documenter setup allows package documentation to be built on the command line by simply executing the `make.jl` script with e.g. `julia --project=docs/ docs/make.jl`, this is can be slow due to all the re-compilation happening in every new Julia session. | |
| pkg> add Documenter | ||
| (@v1.5) pkg> add Revise | ||
|
|
||
| julia> using Revise |
There was a problem hiding this comment.
Might be good to warn here to make sure Revise gets added to the global environment (even though it's implied by (@1.5)>), and not to either as a package dependency or in docs/Project.toml.
| (docs) pkg> dev Example | ||
| [ Info: Resolving package identifier `Example` as a directory at `~/Documents/projects/Example`. |
There was a problem hiding this comment.
This recommendation could be problematic, because it could clone a new package into ~/.julia/dev/Example.jl, if you don't happen to be in the right directory? Perhaps better to use a relative path (pkg> dev . if in package root, or pkg> dev .. if under docs/) ?
| Firstly, we need a Julia module to document. This could be a package generated via | ||
| `PkgDev.generate` or a single `.jl` script accessible via Julia's `LOAD_PATH`. For this | ||
| guide we'll be using a package called `Example.jl` that has the following directory layout: | ||
| Go back to the Pkg REPL and generate a new package: |
There was a problem hiding this comment.
I think it would be really good to advertise PkgTemplates here.
| Now add an `index.md` file to the `src/` directory. | ||
| Since Documenter is a development tool and not a true dependency of your package, create | ||
| a fresh environment in the `docs/` folder, and add Documenter and the Example package | ||
| itself as dependencies: |
There was a problem hiding this comment.
Perhaps also recommend adding a [compat] for Documenter into docs/Project.toml?
| func(x) | ||
| ``` | ||
| ```` | ||
|
|
||
| ### Filtering included docstrings |
There was a problem hiding this comment.
I think heading should be "promoted" now, since ## Adding Some Docstrings was removed:
| ### Filtering included docstrings | |
| ## Filtering included docstrings |
|
I'll close this since it's stale, but hopefully we can re-use bits from here as part of #2321. |
Solves #1413