Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Simplify the guide and focus on iterative package / docs development #1451

Closed
wants to merge 1 commit into from
Closed

Simplify the guide and focus on iterative package / docs development #1451

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
220 changes: 77 additions & 143 deletions docs/src/man/guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,134 +2,123 @@

Documenter is designed to do one thing -- combine markdown files and inline docstrings from
Julia's docsystem into a single inter-linked document. What follows is a step-by-step guide
to creating a simple document.
intended for users who iteratively develop a package and write documentation for it.

## Preliminaries

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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):

Suggested change
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.

## Installation

Documenter can be installed using the Julia package manager.
From the Julia REPL, type `]` to enter the Pkg REPL mode and run
As a package developer you want to keep a single Julia REPL session opened from which you
generate your docs. To make Julia aware of changes to your code and docstrings, you need to
install [Revise.jl](https://github.com/timholy/Revise.jl) first. Enter the Pkg REPL by
pressing `]` and run:

```
pkg> add Documenter
(@v1.5) pkg> add Revise

julia> using Revise
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

```


## Setting up the Folder Structure
## Setting up the Package Structure

!!! note
The function [`DocumenterTools.generate`](@ref) from the `DocumenterTools` package
can generate the basic structure that Documenter expects.

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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it would be really good to advertise PkgTemplates here.


```
Example/
├── src/
│ └── Example.jl
...
```julia
(@v1.5) pkg> generate Example
Generating project Example:
Example/Project.toml
Example/src/Example.jl
```

Note that the `...` just represent unimportant files and folders.
By default the generated Example.jl file contains a `greet()` function. We're going to add a
docstring to it:

We must decide on a location where we'd like to store the documentation for this package.
It's recommended to use a folder named `docs/` in the toplevel of the package, like so
```julia
module Example

```
Example/
├── docs/
│ └── ...
├── src/
│ └── Example.jl
...
```
"""
greet()

Inside the `docs/` folder we need to add two things. A source folder which will contain the
markdown files that will be used to build the finished document and a Julia script that will
be used to control the build process. The following names are recommended
Prints "Hello world!"
"""
greet() = print("Hello World!")

```
docs/
├── src/
└── make.jl
end # module
```

Now create a `docs` folder within the package with the following structure:

## Building an Empty Document

With our `docs/` directory now setup we're going to build our first document. It'll just be
a single empty file at the moment, but we'll be adding to it later on.
```
Example/
├── docs
│ ├── make.jl
│ └── src
│ └── index.md
├── Project.toml
└── src
└── Example.jl
```

Add the following to your `make.jl` file
The `make.jl` file should contain:

```julia
using Documenter, Example

makedocs(sitename="My Documentation")
```

This assumes you've installed Documenter as discussed in [Installation](@ref) and that your
`Example.jl` package can be found by Julia.
and the `index.md` look as follows:

!!! note

If your source directory is not accessible through Julia's LOAD_PATH, you might wish to
add the following line at the top of make.jl
````
# Example.jl Documentation

```julia
push!(LOAD_PATH,"../src/")
```
```@docs
Example.greet()
```
````

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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps also recommend adding a [compat] for Documenter into docs/Project.toml?


!!! note
If you use Documenter's default HTML output the name `index.md` is mandatory.
This file will be the main page of the rendered HTML documentation.
```julia
(@v1.5) pkg> activate Example/docs
Activating new environment at `~/Documents/projects/Example/docs/Project.toml`

Leave the newly added file empty and then run the following command from the `docs/` directory
(docs) pkg> add Documenter

```sh
$ julia make.jl
(docs) pkg> dev Example
[ Info: Resolving package identifier `Example` as a directory at `~/Documents/projects/Example`.
Comment on lines +93 to +94
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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/) ?

```

Note that `$` just represents the prompt character. You don't need to type that.
## Generating docs

If you'd like to see the output from this command in color use
In your REPL you can now include the `make.jl` script:

```sh
$ julia --color=yes make.jl
```

When you run that you should see the following output

```
Documenter: setting up build directory.
Documenter: expanding markdown templates.
Documenter: building cross-references.
Documenter: running document checks.
> checking for missing docstrings.
> running doctests.
> checking footnote links.
Documenter: populating indices.
Documenter: rendering document.
```julia
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 `docs/` folder should contain a new directory -- called `build/`. Its structure should
look like the following
After this, the `docs/` folder should contain a `build/index.html` file. Open this in your
browser to view the generated docs.

```
build/
├── assets/
│ ├── arrow.svg
│ ├── documenter.css
│ ├── documenter.js
│ └── search.js
├── index.html
├── search/index.html
└── search_index.js
```
You can now start developing your package by adding more functions and docstrings and document
them further in `index.md`. Anytime you want to regenerate the docs, run
`include("docs/make.jl)` from the REPL and refresh the `index.html` page in your browser.

!!! note

Expand Down Expand Up @@ -177,61 +166,6 @@ build/
See the [Hosting Documentation](@ref) section for details regarding how you should go
about setting this up correctly.

At this point `build/index.html` should be an empty page since `src/index.md` is empty. You
can try adding some text to `src/index.md` and re-running the `make.jl` file to see the
changes.


## Adding Some Docstrings

Next we'll splice a docstring defined in the `Example` module into the `index.md` file. To
do this first document a function in that module:

```julia
module Example

export func

"""
func(x)

Returns double the number `x` plus `1`.
"""
func(x) = 2x + 1

end
```

Then in the `src/index.md` file add the following

````markdown
# Example.jl Documentation

```@docs
func(x)
```
````

When we next run `make.jl` the docstring for `Example.func(x)` should appear in place of
the `@docs` block in `build/index.md`. Note that *more than one* object can be referenced
inside a `@docs` block -- just place each one on a separate line.

Note that a `@docs` block is evaluated in the `Main` module. This means that each object
listed in the block must be visible there. The module can be changed to something else on
a per-page basis with a `@meta` block as in the following

````markdown
# Example.jl Documentation

```@meta
CurrentModule = Example
```

```@docs
func(x)
```
````

### Filtering included docstrings
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think heading should be "promoted" now, since ## Adding Some Docstrings was removed:

Suggested change
### Filtering included docstrings
## Filtering included docstrings


In some cases you may want to include a docstring for a `Method` that extends a
Expand Down Expand Up @@ -287,11 +221,11 @@ syntax which looks pretty similar to normal markdown link syntax. Replace the co
# Example.jl Documentation

```@docs
func(x)
greet(x)
```

- link to [Example.jl Documentation](@ref)
- link to [`func(x)`](@ref)
- link to [`greet(x)`](@ref)
````

So we just have to replace each link's url with `@ref` and write the name of the thing we'd
Expand All @@ -317,7 +251,7 @@ previous sections. Add the following to that file
## Functions

```@docs
func(x)
greet(x)
```

## Index
Expand Down