-
Notifications
You must be signed in to change notification settings - Fork 473
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Document how to generate docs locally #1413
Comments
Yeah, this would be good to have in the manual somewhere. What I usually do is the following, if you have the standard setup with
You can even drop a |
Yeah, that sounds reasonable. All of this is, of course, obvious in retrospect, but I've struggle with figuring this out, and seen other's do that. |
This came up on Slack too; the Documenter docs are making people run |
It would be nice to write a guide targeted for package developers who interactively write docs and view the result in their browser. I wrote a bit about how to do it from scratch, how to use Revise etc, but unfortunately Revise does not pick up docs for new function definitions it seems :( so I'm not sure if a Revise-first approach is that great |
Docstring updates work for me on Revise
We're happy to accept PRs for the docs, there's always improvements that could be made. |
You are absolutely right 😆. It was late yesterday, I forgot to either export the function from the package or reference it properly in the docs :D. I'll make that PR later tonight then. |
Hm, still experiencing issues when using Revise. I was writing the following for an interactive package development / docs writing guide, but if you follow along and get to the last step... it doesn't pick up the new function with its docs. Can someone reproduce? Guide for package developersThis guide is intended for users who write docs as they develop a new package. For this use case you want to keep a single Julia REPL session open throughout the guide. To keep track of code and docs changes of your package, you need to install Revise.jl globally first. Enter the Pkg REPL by pressing
Go back to the Pkg REPL and generate a new package: (@v1.5) pkg> generate Example
Generating project Example:
Example/Project.toml
Example/src/Example.jl Use your favorite editor to create a
Typically
Open using Documenter, Example
makedocs(sitename="My Documentation") You might also want to add contents to # Example.jl Documentation
Hello world! In your REPL you can now include the julia> cd("Example")
julia> include("docs/make.jl")
[ Info: Precompiling Example [86743d7e-c321-4af5-beac-c79b42746a03]
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages. The Next, we add a new function to our package and document it. Replace the contents of module Example
export func
"""
func(x)
Returns double the number `x` plus `1`.
"""
func(x) = 2x + 1
end And document this function in
In the REPL we can now include the julia> include("docs/make.jl")
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
┌ Warning: no docs found for 'func(x)' in `@docs` block in src/index.md:3-5
│ ```@docs
│ func(x)
│ ```
└ @ Documenter.Expanders ~/.julia/packages/Documenter/pjwqp/src/Expanders.jl:334
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.
Now refresh the |
I think you need
|
With both those changes it doesn't seems to work for me:
Let me try once more from the start... edit: nope. Revise doesn't seem to pick it up for me. That's a bit of a bummer, since it's hard to write a guide that advocates interactive development & viewing docs if this doesn't work out of the box. |
I used this pattern all day yesterday and it worked flawlessly... |
Hm. And I'm pretty sure I used this approach succesfully 3 years ago too. I wonder what's different here. |
Do you have Revise v3? |
|
After restarting the REPL it does pick up changes by the way :). Let's see if we can avoid having to put that step in the guide. |
Ah, I know what is wrong. using Revise, Example
include("docs/make.jl") |
Oh, thanks for pointing that out. Only more reasons to document this workflow! Edit: unfortunately not working (yet) when explicitly |
Seems like the problem is no new docstrings are picked up if the package had no docstrings in the first place. |
I tried to use this approach to generate the docs locally on my Windows 10 machine (julia 1.5.2).
I get the following error:
If I use Should this be mentioned as an alternative or am I missing something ? |
@Nauss |
Thanks !! I'm pretty new to Julia and knew I was missing something ! |
How about adding the following code at the top of default if abspath(PROGRAM_FILE) == @__FILE__
# When running the `make.jl` file as a script, automatically activate the
# `docs` environment and dev-install the main package into that environment
import Pkg
Pkg.activate(@__DIR__)
Pkg.develop(path=joinpath(@__DIR__, ".."))
Pkg.instantiate()
end That code snippet could be discussed in more detail in a rewrite of the Documenter Guide. It would probably help out a lot of people, and with the |
I think my preference would be to have it as a separate script (but one that we could definitely auto-generate for the user). I'd prefer not to re-run all the Pkg machinery every time I do |
Apologies if I've missed something, but I could not find, either by reading the Documenter docs, or googling, how to generate the docs locally while developing. The correct incantation is present in most travis configs, and was pointed out to me on Slack. Unless I have missed something obvious, I think it would be good to document the commands needed. They are not obvious, at least to me. At the very least, this issue can serve as a reminder to myself, since I had to look it up multiple times over the last months as I developed new packages.
This is what I ended up doing, running from a shell. This presumes that the current directory is the package root, and that there exists a docs specific Project.toml. This project file must contain Documenter and the package in question as depdendencies. The following incantations can add the depedencies required, and generate the manifest
After that, the following incantation runs the doc generation.
The text was updated successfully, but these errors were encountered: