Watch docstrings

[halleysfifthinc]

First, LiveServer/servedocs is great! So convenient for working on package docs!

I often simultaneously work on the regular documentation and docstrings, but revising docstrings does not trigger a rebuild of the docs. Could the docstrings be included in what is watched, so that revised docstrings trigger rebuilds?

[tlienart]

Hello,

Glad that you find it useful.

The way servedocs works now is that it scans the docs folder and adds everything to the watcher apart from build files, it also treats the make file separately.

The internal function scan_docs! is effectively what adds everything to the watcher. This could be extended to also add every file in src/.

One thing though I think is that every time a file in src/ changes, the make file has to be re-executed (so that the doc strings can be re-scraped by Documenter).

I don't immediately see blockers to this but if you update a docstring and indeed have to trigger every time, the overhead of the Documenter build will be such that the experience won't be very smooth (you'll update the docstring and then have to wait potentially ten or more seconds for the build to complete). I think that's what prevented me from baking it in in the first place.

Now if you're eager to try, I'm happy to help you navigate the code if you'd like to try to add the src files and open a PR with this as an additional option 😀

[halleysfifthinc]

Good point re: potential for inconvenient delays on every file change in src. Seems like some kind of Revise-like/incremental build option in Documenter would be needed for this feature to be feasible.

[mortenpi]

When you say "the make file has to be re-executed", I presume you mean from scratch in a clean Julia session, as opposed to re-evaluating it in the current session? This should work quite well if you'd somehow manage to integrate this with Revise, as it picks up docstring changes and they are available to Documenter. My usual workflow is something like

$ julia --project=docs/
julia> using Revise
julia> include("docs/make.jl")
...
julia> include("docs/make.jl")
...

and any changes to docstrings between the two includes are reflected in the generated docs. So I don't think it would actually require any changes to Documenter (incremental builds would be still be nice, but for different reasons).

[fredrikekre]

With #154 you use servedocs(...; include_dirs = ["src"]) and put using Revise; Revise.revise() in make.jl.

[halleysfifthinc]

Would that have any downsides/issues when building in GH Actions?

EDIT: Or would that even be necessary if Revise is already loaded in the environment before calling servedocs?