juliadocs / documenter.jl Goto Github PK

Might be worth moving the package to a GitHub org, rather than have it live in my account. Hopefully that would make development more open/approachable for others. JuliaDocs seems like an appropriate name for such an org. (Docile and Lexicon could move as well once they get rewritten for new purposes in 0.5.)

Probably best to merge the two current PRs first to avoid any headaches.

Possible problem may be the current practice of installing Documenter with Pkg.clone("https://github.com/MichaelHatherly/Documenter.jl"), though I believe GitHub should handle the URL redirection for us.

cc @mortenpi

Maybe with screenshots.

I am currently using the rewrite branch of Docile.jl for documentation generation of Hecke and I am very happy with it (thanks). Will Lapidary.jl have the same functionality (or maybe it does already)? In particular I make heavy use of the ability to "dispatch" doc strings. I never dump all docstrings associated to a function at one place of the documentation. Instead I use @(function1(::argument1)) at one place and @(function1(::argument2)) at another place. Will this feature be available in Lapidary?

I've been playing a little bit with Documenter.jl, and like it a lot. In particular I like the possibility of injecting results through {example} as well as using DocTests in script and REPL mode.

For a user guide, I like the idea of illustrating how to use the package with code in a REPL-like session, which separates clearly what you type from what you get; then, using the REPL (or script) blocks seems the way to go, which implies DocTests (unless you disable them completely, which is what I'm currently doing). Yet, DocTests are inconvenient for benchmarks (using @time ...) because of the intrinsic time variations; the way to go seems to be with {example}, which does not insert the julia prompt "julia> " to clearly separate the input from the output. This is clearly circular.

So, I suggest to have the functionality of {example} with the possibility of inserting the "julia> " prompt after parsing. I guess the easy way to go is to introduce the block {example-repl} which executes the code and provides "julia> " for the input. Another possibility, following #5 (which I like a lot), is to have something like

    ```julia-repl-example
        @time whatever()
    ```

Incidentally, the keyword julia-repl could be used to only type julia code (without explicitly using "julia> "), but getting it once the file is parsed.

The current guideline of docstrings (http://julia.readthedocs.io/en/latest/manual/documentation/#documentation) recommends placing arguments and examples under # Arguments and # Examples sections, respectively. But if we splice these docstrings into a Markdown output and render it in HTML, it will result in a too exaggerated heading:

I think we need to reinterpret these docstrings and make them modest headings like **Arguments:**.

Any thoughts?

Currently setting up Documenter for a package is a manual process. Would be nice to have a setup/init/generate function that did some of this automatically.

Once this is a little more stable (please add more):

• LightGraphs
• DataStructures
• Requests
• NumericSuffixes
• PrivateModules
• MergedMethods
• AnonymousTypes

Would be good impetus to migrate to new docstring syntax without (non-generated) repetition in the documentation. Looking at this on some larger projects should give insight into features/bug-fixes needed.

Would be great to have #1 fixed before migrating packages. ;)

Awesome package!

As a test, I converted part of the DataFrames documentation:

https://tshort.github.io/DataFrames.jl/

Many packages use master as the development branch. So with the way deploydocs works, the documentation is for the development branch. It'd be better to have the documentation point to the latest package release. Here are some options to cover this case:

• Use a real "devel" branch, and only use master for releases. This works now.
• Have an option to specify a branch other than master for building, "releases" for example.
• Have deploydocs only build if it's a tagged version.

Better ideas?

One downside to gh-pages is that there's only one branch. You can't have documentation for different releases or for the development version. It'd be nice to have a way around that. Maybe deploydocs could write to a different repo (DataFrames.jl-devdocs) for development commits.

Is it possible to get an index for the current file? I've tried it a couple of ways:

• https://github.com/tshort/DataFrames.jl/blob/master/docs/src/lib/manipulation.md
• https://github.com/tshort/DataFrames.jl/blob/master/docs/src/lib/maintypes.md

Because the list of docstrings listed isn't in the contents on the left (they aren't headings), I'd like to put an index at the top of the current file.

I believe there is a potential security concern: when there are any problems in deploying the docs, it is possible that the key github_api_key is printed when the remote address is echoed. It may be necessary to catch any possible errors in the function deploydocs by using try.

The following case fails to pass REPL doctest:

julia> for (i, nt) in enumerate("ATNGNNT")
           if nt == 'N'
               println("N in position ", i)
           end
       end
N in position 3
N in position 5
N in position 6

This would be because Lapidary.jl doesn't support capturing output to STDOUT stream. Is that possible to support testing output?

Hi,

On Bio.jl travis builds for julia v0.4 on OSX we've started to experience build failures even though all tests pass, the log indicating something freezes or becomes non-responsive after docs deployment. In the travis log it will say "Skipping docs deployment" for a merge into the master branch, and then will be non responsive for 10m. So I'm just investigating to see if this is Documenter.jl related.

This is the current log for Bio.jl master: https://travis-ci.org/BioJulia/Bio.jl/jobs/128102434

Many thanks,
Ben.

Hi,

Could you please help me debug this example? https://github.com/juliohm/ImageQuilting.jl

I didn't create a personal access token on GitHub, is it required for the automatic commit on gh-pages?

I can't manage to get tables to work right:

• Source: https://github.com/tshort/Maker.jl/blob/master/docs/src/terminology.md
• Result: https://tshort.github.io/Maker.jl/stable/terminology/

I've tried various indenting approaches and use of pipes.

I get an error message at the bottom of the webpage, it doesn't affect the website though.

Re: MichaelHatherly/Docile.jl#147 (comment), cc @hayd

Currently just a placeholder name, though slightly "thematic". See meaning https://en.wikipedia.org/wiki/Lapidary_%28text%29.

Options for name change:

• something simple and unsurprising, i.e. MakeDocs.jl
• a more thematic name, but not too obscure.

The following table is not rendered correctly in HTML:

docs/src/man/seq.md

The following table summarizes common sequence types that are defined in the
`Bio.Seq` module:

| Type                               | Symbol type      | Type alias          |
| ---------------------------------- | ---------------- | ------------------- |
| `BioSequence{DNAAlphabet{4}}`      | `DNANucleotide`  | `DNASequence`       |
| `BioSequence{RNAAlphabet{4}}`      | `RNANucleotide`  | `RNASequence`       |
| `BioSequence{AminoAcidAlphabet}`   | `AminoAcid`      | `AminoAcidSequence` |
| `BioSequence{CharAlphabet}`        | `Char`           | `CharSequence`      |

browser view

I guess this is because it is converted to a weird Markdown table:

docs/build/man/seq.md

The following table summarizes common sequence types that are defined in the `Bio.Seq` module:


                            Type |     Symbol type |          Type alias
-------------------------------: | --------------: | ------------------:
   `BioSequence{DNAAlphabet{4}}` | `DNANucleotide` |       `DNASequence`
   `BioSequence{RNAAlphabet{4}}` | `RNANucleotide` |       `RNASequence`
`BioSequence{AminoAcidAlphabet}` |     `AminoAcid` | `AminoAcidSequence`
     `BioSequence{CharAlphabet}` |          `Char` |      `CharSequence`

As you see, the first header line is right aligned in the converted Markdown file.

My current workaround is explicitly writing left-aligned table like below:

docs/src/man/seq.md

| Type                               | Symbol type      | Type alias          |
| :--------------------------------- | :--------------- | :------------------ |
| `BioSequence{DNAAlphabet{4}}`      | `DNANucleotide`  | `DNASequence`       |
| `BioSequence{RNAAlphabet{4}}`      | `RNANucleotide`  | `RNASequence`       |
| `BioSequence{AminoAcidAlphabet}`   | `AminoAcid`      | `AminoAcidSequence` |
| `BioSequence{CharAlphabet}`        | `Char`           | `CharSequence`      |

This is converted to:

docs/build/man/seq.md

Type                             | Symbol type     | Type alias         
:------------------------------- | :-------------- | :------------------
`BioSequence{DNAAlphabet{4}}`    | `DNANucleotide` | `DNASequence`      
`BioSequence{RNAAlphabet{4}}`    | `RNANucleotide` | `RNASequence`      
`BioSequence{AminoAcidAlphabet}` | `AminoAcid`     | `AminoAcidSequence`
`BioSequence{CharAlphabet}`      | `Char`          | `CharSequence`     

This looks as I expected:

browser view

I am trying to generate documentation from the source files. From what I understand all that I need to do is to call makedocs(). However, I get the following error when I invoke the above API.

          _

_ _ ()_ | A fresh approach to technical computing
() | () () | Documentation: http://docs.julialang.org
_ _ | | __ _ | Type "?help" for help.
| | | | | | |/ ` | |
| | || | | | (| | | Version 0.5.0-dev+2440 (2016-02-01 02:22 UTC)
/ |_'|||__'| | Commit 2bb94d6 (8 days old master)
|__/ | x86_64-apple-darwin13.4.0

julia> using Lapidary

julia> makedocs()
ERROR: MethodError: cd has no method matching cd(::Lapidary.##19#20{ASCIIString,ASCIIString,ASCIIString,Bool,Array{Tuple{Lapidary.AbstractAction,Lapidary.AbstractAction,Lapidary.AbstractAction,Vararg{Lapidary.AbstractAction}},1}}, ::Void)
Closest candidates are:
cd(::Function)
cd(::Function, ::AbstractString)
in eval(Core.#eval, Module, Any) at /Applications/Julia-0.5.0-dev-2bb94d6f99.app/Contents/Resources/julia/lib/julia/sys.dylib:-1

julia>

Am I missing something here ?

This is a small RFC to discuss a possible extension of the make.jl

In a nutshell, the make.jl script could take arguments to allow the user have a bit more control over what it does. I am thinking basically how mkdocs works. So, you would call it like julia make.jl <command>, where the command could be build, clean, deploy, serve etc.

You could also have more arguments, to give even more power to the user, without them having to make changes to the script (e.g. specify the target format, --debug etc). Also, having a serve command would be a first step in addressing #11.

In the make.jl it would look something like this

using Documenter, PkgName
Documenter.run(ARGS; config...)

The implementation actually wouldn't necessarily conflict with the way the scripts work currently, since we can keep makedocs and deploydocs function (and would probably call them in run), even though perhaps in the long term they should be deprecated. Also, build could be the default command, so julia make.jl would work as it does currently.

One more benefit would be that some things would become a bit more explicit. For example, deploydocs currently semi-magically decides if it should do something or not. The explicitness could maybe help with testing as well.

I got the following error:

Documenter: setting up build directory.
ERROR: LoadError: UndefVarError: walkdir not defined
 in exec at /home/jared/.julia/v0.4/Documenter/src/modules/Builder.jl:229
 in process at /home/jared/.julia/v0.4/Documenter/src/modules/Builder.jl:195
 in process at /home/jared/.julia/v0.4/Documenter/src/modules/Builder.jl:191
 in anonymous at /home/jared/.julia/v0.4/Documenter/src/Documenter.jl:120
 in cd at ./file.jl:22
 in makedocs at /home/jared/.julia/v0.4/Documenter/src/Documenter.jl:119
 in include at ./boot.jl:261
 in include_from_node1 at ./loading.jl:304
 in process_options at ./client.jl:280
 in _start at ./client.jl:378

when running makedocs(), using Julia version

Julia Version 0.4.4-pre+35
Commit 1a9429e* (2016-02-12 13:21 UTC)
Platform Info:
  System: Linux (x86_64-linux-gnu)
  CPU: Intel(R) Core(TM) i7 CPU       Q 820  @ 1.73GHz
  WORD_SIZE: 64
  BLAS: libopenblas (USE64BITINT DYNAMIC_ARCH NO_AFFINITY Nehalem)
  LAPACK: libopenblas64_
  LIBM: libopenlibm
  LLVM: libLLVM-3.3

It would be nice to add code from a test directly into the documentation. Many times examples are included in the package as tests. As the package gets updated, these tests get updated, but corresponding tutorials in documentation might not. If the documentation had a way of getting the code directly form the tests, then it would alleviate this problem. The only issue would be that there would need to be a way to annotate the file a bit more, i.e. add a bunch of strings/markdown to make it a tutorial instead of just a test.

using Lapidary throws an error UndefVarError: Footnote not defined.

If you're extending a function and adding documentation, I suspect you only want to display the new docstring rather than it appended to to documentation from other Modules.

I suspect the rule is:

1. If documentation is defined in MyPackage use only that.
2. if no documentation is defined use whatever there is e.g. from Base.

I think this was in the Docile rewrite branch but the api has changed since then?

Using Lexicon, we could just write all docstrings from a module into a markdown file. How do we do this with Documenter? I basically want to avoid having to manually add what I want documented to index.md since that means every time a new function is created, it needs to also be added to that file.

Thanks (again) for implementing MichaelHatherly@7168524. I really like its functionality. Here, I'd like to point out few issues I have encountered while using it:

• It seems to me that {repl} is not redirecting correctly STDOUT and STDERR. Actually, when an event related to STDERR is encountered, the whole {repl} block is simply parsed as a code block. Warnings and info messages are not displayed (but do not cause a code block as the error).
• The trick (see your comment) of using nothing # hide to suppress output (@time do_somethin()) does not working in {repl}.
• I'm getting a weird error (on Julia v0.4) which leads to hanging in "Documenter: skipping docs deployment" (in Julia 0.5 it simply hangs there). The context is two files which use named {repl} blocks which are independent. Taking away either file from the src/ directoryyields no error, but merging the files into one does.) It is worth saying that the files created in build/ appear correctly. The error is

ERROR (unhandled task failure): readcb: bad file descriptor (EBADF)
 in yieldto at /usr/local/julia/julia-d829429d34/lib/julia/sys.dylib
 in wait at /usr/local/julia/julia-d829429d34/lib/julia/sys.dylib (repeats 2 times)
 in wait_readnb at ./stream.jl:374
 in eof at ./stream.jl:96
 in watchbuffer at /Users/benet/.julia/v0.4/Documenter/src/modules/DocChecks.jl:343
 in anonymous at ./task.jl:447

Can be useful to run doctests without having to build docs as well.

it seems that there is a problem in documenting macros..

macros.md

## Macros

    {docs}
    @rimport

julia make.jl

ERROR: LoadError: MethodError: `convert` has no method matching convert(::Type{Base.Markdown.MD}, ::Void)
This may have arisen from a call to the constructor Base.Markdown.MD(...),
since type constructors fall back to convert methods.
Closest candidates are:
  Base.Markdown.MD(::Any...)
  call{T}(::Type{T}, ::Any)
  convert{T}(::Type{T}, !Matched::T)
  ...

Hey, I am having issues getting the LaTeX from the docstrings to display. For example, following the Julia documentation documentation, I use the following docstring:

doc"""
HeatProblem

Wraps the data that define a 2D linear heat equation problem:

`` $$ u_t = Δu + f(x,t) $$ ``

(truncated for simplicity). In my documentation I use {docs} HeatProblem which transforms into Markdown code like

HeatProblem

Wraps the data that define a 2D linear heat equation problem:

`` $ (generic function with 34 methods) u_t = Δu + f(x,t) $ (generic function with 34 methods) ``

And using

deploydocs(deps   = Deps.pip("mkdocs", "python-markdown-math"),
    repo = "github.com/ChrisRackauckas/DifferentialEquations.jl.git",
    julia  = "0.4.5",
    osname = "linux")

to build I get results that can be seen at the documentation here. Is there way to get the LaTeX to render?

I am getting an error generating documentation for PETSc.jl using the modules=[PETSc] keyword.

jared@k475:~/.julia/v0.4/PETSc/doc$ julia4 ./make.jl 
Documenter: setting up build directory.
Documenter: copying assets to build directory.
Documenter: expanding markdown templates.
 !! No docs for 'Base.!' from provided modules. [src/index.md]
 !! No docs for 'Base.!=' from provided modules. [src/index.md]
 !! No docs for 'Base.*' from provided modules. [src/index.md]
 !! No docs for 'Base.+' from provided modules. [src/index.md]
 !! No docs for 'Base.-' from provided modules. [src/index.md]
 !! No docs for 'Base..*' from provided modules. [src/index.md]
 !! No docs for 'Base../' from provided modules. [src/index.md]
 !! No docs for 'Base..\' from provided modules. [src/index.md]
 !! No docs for 'Base..^' from provided modules. [src/index.md]
 !! No docs for 'Base.==' from provided modules. [src/index.md]
 !! No docs for 'Core.===' from provided modules. [src/index.md]
 !! No docs found for '=>'. [src/index.md]
 !! No docs for 'Base.>=' from provided modules. [src/index.md]
 !! No docs for 'Base.@doc' from provided modules. [src/index.md]
 !! No docs for 'Base.@eval' from provided modules. [src/index.md]
 !! No docs found for '@v_str'. [src/index.md]
 !! No docs found for 'AO'. [src/index.md]
ERROR: LoadError: "AO_" is not defined in module Main
 in error at ./error.jl:21
 in which_module at ./reflection.jl:315
 in call at ./docs/bindings.jl:8
 in expand at /home/jared/.julia/v0.4/Documenter/src/modules/Expanders.jl:153
 in expand at /home/jared/.julia/v0.4/Documenter/src/modules/Expanders.jl:75
 in expand at /home/jared/.julia/v0.4/Documenter/src/modules/Expanders.jl:76
 in expand at /home/jared/.julia/v0.4/Documenter/src/modules/Expanders.jl:69
 in process at /home/jared/.julia/v0.4/Documenter/src/modules/Builder.jl:195
 in process at /home/jared/.julia/v0.4/Documenter/src/modules/Builder.jl:196
 in process at /home/jared/.julia/v0.4/Documenter/src/modules/Builder.jl:191
 in anonymous at /home/jared/.julia/v0.4/Documenter/src/Documenter.jl:120
 in cd at ./file.jl:22
 in makedocs at /home/jared/.julia/v0.4/Documenter/src/Documenter.jl:119
 in include at ./boot.jl:261
 in include_from_node1 at ./loading.jl:304
 in process_options at ./client.jl:280
 in _start at ./client.jl:378
while loading /home/jared/.julia/v0.4/PETSc_current/doc/make.jl, in expression starting on line 3

If I have understood the documentation correctly, it should be looking for AO_ in PETSc, not Main.

The index.md file contains every name used in the PETSc module (and is auto generated), some of which are defined in different modules, but AO_ is defined within PETSc.
The make.jl file and the script that creates index.md are here: https://github.com/JuliaParallel/PETSc.jl/tree/doc/doc

Most likely this should also go into build as index.md.

Hi

I'm trying to include a logo for use with material-mkdocs in my documentation. I had assumed that as long as I put it in docs/src/assets/images (because I know Lapidary puts such a directory in the build (i.e. docs/build/assets/images) lapidary would include it. However Lapidary does not do this, it simply creates docs/build/assets/two favicon files here. Can I direct Lapidary to include files in the build? Or do I have to manually do this in the make.jl file after calling makedocs()?

Thanks,
Ben.

1. It seems that mkdocs search function only searches over headings. A DocsNode is now rendered as normal text only, which makes the search not able to pick up the DocsNode. Perhaps we should render the doc.object.binding as ### {doc.object.binding} ?
2. Additionally, the search function of mkdocs does not separate words connected with dot. For example, search is not able to pick up Lapidary.Path if we are looking for Path.

By editing the render function for DocsNode like this

function render(io, mime, doc::DocsNode, env)
    print(io, "\n")
    print(io, "### ", doc.object.binding.var)
    println(io, " (", doc.object.binding.mod, ", *", doccat(doc.object), "*).\n")
    writemime(io, mime, doc.docs)
    println(io, "\n")
end

I am able to get better search results. Not sure if it is reasonable.

Am I calling this incorrectly / from the wrong directory?

(Lapidary/docs)$ julia build.jl                                                                                                       
ERROR: LoadError: cannot find `src` directory `src`.
 [inlined code] from ./error.jl:21
 in call at /Users/andy/.julia/v0.5/Lapidary/src/types.jl:34
 in anonymous at /Users/andy/.julia/v0.5/Lapidary/src/Lapidary.jl:27
 in cd at ./file.jl:47
 in makedocs at /Users/andy/.julia/v0.5/Lapidary/src/Lapidary.jl:26
 in include at ./boot.jl:262
 in include_from_node1 at ./loading.jl:401
 in process_options at ./client.jl:245
 in _start at ./client.jl:301
while loading /Users/andy/.julia/v0.5/Lapidary/docs/build.jl, in expression starting on line 3

 (Lapidary/docs)$ cd ..                                                                                                                                 

 (v0.5/Lapidary)$ julia docs/build.jl
ERROR: LoadError: cannot find `src` directory `src`.
 [inlined code] from ./error.jl:21
 in call at /Users/andy/.julia/v0.5/Lapidary/src/types.jl:34
 in anonymous at /Users/andy/.julia/v0.5/Lapidary/src/Lapidary.jl:27
 in cd at ./file.jl:47
 in makedocs at /Users/andy/.julia/v0.5/Lapidary/src/Lapidary.jl:26
 in include at ./boot.jl:262
 in include_from_node1 at ./loading.jl:401
 in process_options at ./client.jl:245
 in _start at ./client.jl:301
while loading /Users/andy/.julia/v0.5/Lapidary/docs/build.jl, in expression starting on line 3

There are cases where it would be useful to auto generate documentation for particular files, allowing more granular control than the current @autodoc module.

Hello, I am trying to use Documenter.jl to build the documentation for my package DifferentialEquations.jl. My attempt can be found here and follows the guide. When I run the make.jl file, I receive the output:

Documenter: setting up build directory.
Documenter: copying assets to build directory.
Documenter: expanding markdown templates.
Documenter: building cross-references.
Documenter: running document checks.
 !! 32 docstrings potentially missing:

and then it proceeds to list every function with a docstring. The functions I put in the index.md file to test on:

{docs}
DifferentialEquations

{docs}
findboundary(elem,bdFlag=[])

Do not change in the output build in /build/index.md. This is on both a Windows and Linux machine.

This is going to be a little speculative.

Back over in MichaelHatherly/Lexicon.jl#129 I suggested the following output:

That is:

• function link
• signature w/ source links
• docstring

The tricky thing here is that the convention is that the first part (of each block?) has the simplified signature, however it seems to me that there are two placements for the extracted docstring:

1. in the manual (inline surrounded by discussion)
2. in the api section (e.g. with all methods listed in alphabetical / module order)

Generally I prefer the in-situ functions, but it can be useful just to list them all out (sometimes it can seems that topics are separated somewhat arbitrarily).

http://lightgraphsjl.readthedocs.org/en/latest/pathing/ has good example of in-situ docs.
http://lexiconjl.readthedocs.org/en/latest/api/Lexicon/ good example of api docs.

I'm of the opinion that having both (in-situ and api sections) is the best policy...

Potentially the API to have an additional pass to add the full method table (of methods defined in the Package) with links. This does have the problem of "where to link the function to: the in-situ or the api version of the method?

It's probably not good to be giving Travis personal access tokens, as this gives access to a users whole account (including private repositories, ability to change/delete lots of things).

A better approach would be to use GitHub deploy keys. Here is some code I wrote a while back when thinking about how to do this (this uses a slightly different approach of using Travis's encrypt functionality, which requires that the Travis command line tools be installed, but it is probably easier to use your approach of pasting it in to the Travis repository settings).

At the moment, all the md files are built and dumped into build.

If using mkdocs (#10) these have to be specified in the yaml. One could do the same in a top level latex file to input these and add style. This seems like a duplication of effort (specifying the ordering).

I would propose, either:

1. mkdocs.yml pages-section is required, use this to decide the ordering and naming of sections. Warn/error if sections are missing in both src or yaml. Use this for generating single-page html/latex.
2. makedocs function allows passing of this ordering (as title => filename pairs). Warn/error if sections missing or do not exist in both src or yaml.

My preference is the mkdocs.yml as this already exists, and allows nested files etc.

This is crucial in compiling to a single document (e.g. #4).

That way some interesting documentation can be generated!

Hi,

I've set up a Lapidary docs system on the master branch at BioJulia/Bio.jl, with a make.jl file and I've followed the instructions to get travis.yml set up appropriately, and I've given Travis CI a personal access token I've generated. I've also set up mkdocs.yml, and made sure make.jl also includes the deploydocs(repo = "github.com/BioJulia/Bio.jl.git") function. However pushing to master does not auto-generate new documentation. In addition, if I navigate to the docs directory, and do julia make.jl I get the following output:

LAPIDARY: setting up build directory.
LAPIDARY: copying assets to build directory.
LAPIDARY: parsing markdown templates.
LAPIDARY: expanding parsed template files.
LAPIDARY: generating cross-reference links.
LAPIDARY: running doctests.
LAPIDARY: checking document consistency.
LAPIDARY: writing document to file.
LAPIDARY: skipping docs deployment.

I'd like to know why would it skip deployment on the last step. It makes the /build directory and make splices in the doctoring and such brilliantly, I just don't know why it's not doing the mkdocs and deployment steps at the last stage of the process.

Any help with this is greatly appreciated.

Best,
Ben W.
BioJulia.

Currently I only have a latest folder in the gh-pages branch. How to generate the stable folder automatically?

I'm getting the following with makedocs:

LoadError: duplicate header id 'deprecations' 

https://github.com/JuliaStats/DataFrames.jl/blob/master/NEWS.md

For some files, it's common to have multiple headings with the same name.

A very minor thing: have doc/ as the default directory for the documentation (instead of docs/)?

That is, change to doc/ in Documenter's documentation and have the potential future generate() function ( #57 ) generate doc/ by default as well.

My impression is that more packages store the docs in doc/ currently, including Julia itself. So it would be purely in the interest of consistency, since people will most likely stick with whatever Documenter.jl suggests.

When writing documentation you usually want to see it rendered.

For example mkdocs watches the docs_dir for any changes, and rebuilds the site each time there is a change. We could watch the docs/src directory and rebuild docs/build upon changes (then mkdocs would see this...). Or build once or watch based on cli arg.

Of course, this could be another package, it does sound like feature creep!

For packages that would like to keep a NEWS.md file (or some other file) of changes having issue and pr links get added automatically could be useful, similar to Julia's https://github.com/JuliaLang/julia/blob/master/doc/NEWS-update.jl.

Syntax:

... [#59](@ref) ...

expands to

... [#59](https://github.com/MichaelHatherly/Documenter.jl/issues/59) ...

which probably wouldn't conflict with other uses.

This might be a cleaner solution to using {...} in the first line.

IMO it also has the benefit of being more "honest". In the sense that:

julia> print(1)
1

is not julia. That said these could render to a julia code block...

Use the same Modules = and Order = options from @autodocs in @index to allow for more fine-grained control of docstring index construction, i.e.

```@index
Pages   = ["foo.md", "bar.md"]
Modules = [Foo, Bar]
Order   = [:function, :type]
```