ANN: Documenter.jl

[Michael Hatherly]

I’m please to announce the initial release of Documenter.jl — a documentation generator for Julia.

The package docs are here.

The package is still a work-in-progress, but now has sufficient features to make a stable release worth while. Major breaking changes should hopefully be few and far between from now on.

If you have already been making use of the package, which quite a few of the community have been, then I’d would like to extend my thanks to you for helping file bug reports, feature requests, and pull requests.

Please do upgrade your .travis.yml configuration to reflect the fact that Documenter is now tagged and available from METADATA. All that should be needed is to replace either

Pkg.clone("https://github.com/MichaelHatherly/Documenter.jl")

or, more recently,

Pkg.clone("https://github.com/JuliaDocs/Documenter.jl")

with

Pkg.add("Documenter")

and your build scripts should work fine. Any problems you happen to run into should, as always, be reported on the GitHub issue tracker. master will be more unstable from this point on.

If you do have a publicly available package that is making use of Documenter, then please do add a link to the Examples page if you’d like.

Finally: I’d like to thank one of our Google Summer of Code students, Morten Piibeleht, who is developing some great new features for the package over the summer.

— Mike

[Uwe Fechner]

Hello,

I installed Documenter and followed the tutorial. Now I would like to convert the documentation in html WITHOUT deploying
it to github. How can I do this?

Uwe

[Chris Rackauckas]

Uwe, take a look here. You can use mkdocs build then mkdocs serve to do so (I think serving will actually build the docs too so that might be redundant). 

Glad to see this package announcement! It really is a spectacular documentation system and will really serve the Julia community. I hope that the GSoC student implements the documentation from tests since I still see a lot of Julia packages saying saying things similar to "to learn the package, take a look at the tests". I think that if we start generating tutorials/examples directly from these tests, add them to this documentation system which pulls everything from docstrings, and allow it to generate parts of the Github README, we will be in a heaven of "documentation which is generated from the actual tested code and thus up to date".

[Michael Hatherly]

You’ll need to use mkdocs like Chris mentions. Install it using pip install mkdocs, run julia docs/make.jl to generate the markdown files, and then run mkdocs serve (or mkdocs build). That is an unfortunately long route to get to the final product, but work is currently being done to remove mkdocs from the process and use a pure Julia solution instead, which is the main aim of the summer of code work being done.

— Mike

[Michael Hatherly]

Thanks for doing that write up Chris. I’ve not forgotten about the docs from tests issue :) it will get implemented sooner or later I’m sure, either by me or when someone else needs it. Definitely a worthwhile feature to have I think.

— Mike

[Daniel Carrera]

I can't find any documentation for this module. How does it work? How do you use it? What mark up language does it use? etc etc. The README file is basically blank, and the docs directory doesn't seem to contain any actual docs.

Daniel.

[Eric Forgy]

A documentation package with no documentation? How can that be? :D

[Kristoffer Carlsson]

Click the docs button in the README

https://juliadocs.github.io/Documenter.jl/stable

[Michael Hatherly]

There's two links in the README (the blue "docs" badges), one in the repo header, and one in the second paragraph of the first post of this thread :)

-- Mike

[Daniel Carrera]

No there aren't. I am looking at the README right now. It is nearly blank. It has two lines on installation, one line on project status, and two sentences on "contributing and questions". The second of those sentences has a link to the issues page.

I don't want to be rude, but the README file of a documentation package should have at least as much documentation as the README files of other non-documentation Julia packages. It is normal in Julia packages to have documentation in the README, often including a link to more detailed documentation in readthedocs.org or similar.

One bit of constructive criticism for the documentation: in the features list, you should state what markup language you are using. Is it Markdown? Probably, but that's something that should be stated explicitly. Maybe add some examples showing the use of Markdown.

Cheers,

Daniel.

[Michael Hatherly]

I don’t want to be rude

No worries, I’m not taking your criticism at rudeness.

It has two lines on installation, one line on project status, and two sentences on “contributing and questions”.

You’ve missed out the section called “Documentation” there. Perhaps you’re
viewing a cached version of the README that isn’t showing it for some reason.
Not sure why that would be, but there definitely is a section between
“Installation” and “Project Status” linking directly to the docs. Could you
post a screenshot of what the README look like to you?

the README file of a documentation package should have at least as much documentation as the README files of other non-documentation Julia packages

Adding additional duplicated documentation to the README when there is already
a substantial amount of documentation elsewhere isn’t really worth doing in my
view — especially when the complete docs are a single click away. Note that
there is an open issue for automatically generating the README
from files in docs/src, which would go some way to resolve the duplication
problem.

you should state what markup language you are using.

That is mentioned directly above the feature list in the summary line:

A package for building documentation from docstrings and markdown files.

so I didn’t feel the need to duplicate that again in the feature list.

Maybe add some examples showing the use of Markdown.

There’s already a number of examples that illustrate the syntax in the “Guide”
page and “Syntax” page.

PRs to improve the docs are most welcome since it’s always difficult to read
the docs from the point-of-view of a new user. Thanks for taking the time to
have a look at the package Daniel.

— Mike

[Daniel Carrera]

Hi Mike,

Thanks for being cool about my (hopefully constructive) criticism. I'm very glad that there is now a package for documenting Julia code, and I expect to use it in the future. So thanks for that.

On 18 June 2016 at 15:20, Michael Hatherly <michael...@gmail.com> wrote:

It has two lines on installation, one line on project status, and two sentences on “contributing and questions”.

You’ve missed out the section called “Documentation” there. Perhaps you’re
viewing a cached version of the README that isn’t showing it for some reason.

The "Documentation" section has literally one sentence (one I don't really understand). Here is the entire section from the raw file:

--------------------------

# Documentation

Documentation is built automatically with help from *MkDocs* on *Travis CI* and hosted by *GitHub Pages*.

[![][docs-latest-img]][docs-latest-url] [![][docs-stable-img]][docs-stable-url]

## Project Status

--------------------------

 

the README file of a documentation package should have at least as much documentation as the README files of other non-documentation Julia packages

Adding additional duplicated documentation to the README when there is already
a substantial amount of documentation elsewhere isn’t really worth doing in my
view

Well, the point of a README file so to have useful information about the package. The current file is close to empty (but maybe I'm looking at an old version?). Also, how are people going to find documentation without a link in the README? Lastly, it is standard for Julia packages to have a short introduction and documentation in the README. This file is also often used as a gateway to the rest of the documentation. For example:

https://github.com/plotly/Plotly.jl

https://github.com/stevengj/PyCall.jl

https://github.com/JuliaLang/ODE.jl

https://github.com/staticfloat/Opus.jl

Notice that PyCall has a very extensive README. But even a very short README like the one from Opus.jl still includes sample code, and some information about usage. I would call Opus.jl an example of a poorly documented module, and the author still thought it was a good idea to explain a bit about how the package works and what it does. In contrast, with Documentation.jl the only way I know to find information is to go to my email client and find this thread.

you should state what markup language you are using.

That is mentioned directly above the feature list in the summary line:

A package for building documentation from docstrings and markdown files.

so I didn’t feel the need to duplicate that again in the feature list.

It is not duplication, it is clarity. I saw that line too. This is partly why I GUESSED that maybe Markdown is used. That, and the file that Julia docs often use Markdown; but I only know that because I've been around Julia for a while. The one sentence you are referring to does not in any way say or imply that you can use markdown syntax inside docstrings. I mean... cant you actually use Markdown inside docstrings? I suspect you can, but I don't actually know for sure. I know that in your email you basically said "yes". But how much of Markdown do you support? Which flavor? I think that these are things I should have been able to infer easily since this is the core feature of your package (unless I misunderstood the package).

There is such a thing as too much duplication, but you are nowhere near having that problem. Currently the documentation is closer to the opposite end, where you tend to write the bare minimum and it seems like you expect users to try to guess what you might have been thinking. That's not where you want to be. I would also argue that it's better to err on the side of being "too clear", rather than not clear enough.

 

Maybe add some examples showing the use of Markdown.

There’s already a number of examples that illustrate the syntax in the “Guide”
page and “Syntax” page.

I did scan at the Syntax page.  On a second look, I do see examples of Markdown. If I didn't already know some Markdown, I think I would have missed it on the second look as well. The thrust of this section seems to be about @doc, @autodocs, and the other blocks in the package. I didn't imagine that the examples were supposed to introduce some bits of Markdown syntax.

 

PRs to improve the docs are most welcome since it’s always difficult to read
the docs from the point-of-view of a new user. Thanks for taking the time to
have a look at the package Daniel.

I think it's great that now there is a documentation package for Julia and I'm very glad you wrote one. So thank you for that. If I get the time, I will make a PR.

Cheers,

Daniel.

[Michael Hatherly]

Here is the entire section from the raw file

“Raw file” is the key here: those are image links below the sentence. Look at
the rendered version on the GitHub repo rather and you’ll be able to see the
docs badges correctly. That’s the most common way people will be browsing for
packages. I can try make those more obvious/informative in their raw form though.

without a link in the README

There are links in the README.

it is standard for Julia packages to have a short introduction and documentation in the README.

I’m aware of what some packages chose to do. I have chosen to provide very
clear links to the documentation instead. I would say that part of the reason
that packages make use of the README for their documentation is that there
have not been many other viable options. To me a README should provide more
developer-orientated details of a project, that’s just my view though :)

I saw that line too.

I GUESSED that maybe Markdown

If you saw that line then “guessed” can’t really be the right word.
I’ll add a more clear point in the introduction though.

use markdown syntax inside docstrings

That is covered by the main Julia manual. A link could be provided to that, but
generally the route potential users should be taking is to read the Julia
manual first and then go looking for packages that they need.

If I didn’t already know some Markdown

Yes, a link could be provided to resources that teach markdown. I’d be fine
with that, but Documenter’s manual is not the place to teach markdown syntax
from scratch.

I think it’s great that now there is a documentation package for Julia and I’m very glad you wrote one. So thank you for that. If I get the time, I will make a PR.

Thanks, and I’d also like to thank you for all your input on the docsystem
discussions in #3988 and elsewhere.

— Mike

​

[Mauro]

As others in this thread, I was confused by (and thus ignored) those
documentation badges the first time I saw them, even though I was using
the travis badges regularly. To help badges-challenged people like
myself, maybe add a normal link too? In fact, I like the setup: all the
badges along the top and prose afterwards. This serves both the badgers
and non-badgers. (I agree though that you can keep the readme short if
other docs are provided.)

PS: Thanks, Mike, for all your work on the Julia documentation system!
It has come along nicely and a very long way since you started working
on it.

[Michael Hatherly]

badgers and non-badgers

:D

In fact, I like the setup: all the badges along the top and prose afterwards.

Yes, that’s a good compromise. Happy to make a change like that.

— Mike

[Daniel Carrera]

On 18 June 2016 at 18:34, Michael Hatherly <michael...@gmail.com> wrote:

Here is the entire section from the raw file

“Raw file” is the key here: those are image links below the sentence. Look at
the rendered version on the GitHub repo rather and you’ll be able to see the
docs badges correctly. That’s the most common way people will be browsing for
packages. I can try make those more obvious/informative in their raw form though.

Of course I began with the rendered file on the browser. It honestly did not cross my mind that those pictures were links. My eyes just moved past them like background noise every time I looked at this page. Please don't use buttons or icons to serve the purpose of links. Really. These are basic usability standards. If you meant to have a link, use a link. Please, trust me on that.

 

without a link in the README

There are links in the README.

It took a conversation with you over several emails for me to "find" those links. This really isn't good. I'm sorry, but it isn't. I doubt that I will be the only person who will not interpret those little pictures as links that I'm supposed to click on to get the documentation. And really, what do those pictures really say? They say "docs|stable" and "docs|latest". How the heck is that supposed to mean "click here"? It sounds like you are labelling the present README (the one I'm looking at) as the stable and the latest. Those pictures look like badges.

 

it is standard for Julia packages to have a short introduction and documentation in the README.

I’m aware of what some packages chose to do. I have chosen to provide very
clear links to the documentation instead.

Your "very clear links" were missed by me multiple times, and were missed by Mauro, and I swear that I would have continued to miss them if you had not told me in this email that those pictures are links. They do not loo like links. These are *NOT* very clear links. They really really are not.

I just did a test. I gave my laptop to my wife and asked her to find the documentation. She said "good question, I have no idea". Then I pointed at the little pictures and said "would you believe that those are links that take you to the documentation?" and she said "no, I would not have guessed that". So there are at least three people in the universe that did not think that you had clear links. That means that there are probably more, and the links aren't as clear as you imagine.

 

I would say that part of the reason
that packages make use of the README for their documentation is that there
have not been many other viable options. To me a README should provide more
developer-orientated details of a project, that’s just my view though :)

Julia is a programming languages. We are all developers. The nature of GitHub is that when you go to the GitHub page of a project you see an HTML rendering of the README file. This makes the README file the effecting *front* *page* for the project, and every project that uses GitHub should treat it as such. The README is literally the first thing that your users are going to see about your project. This isn't even a Julia thing, it's a Github thing. I just searched for Python projects on Github and look:

https://github.com/donnemartin/awesome-aws

https://github.com/nbrochu/requests-respectful

Try other Github projects. The README is just the front page in Github and you have to accept that that is how Github uses the README file.

If you saw that line then “guessed” can’t really be the right word.
I’ll add a more clear point in the introduction though.

"Guessed" is exactly the right word. And the guess was based partly on my previous knowledge that Markdown is often used in Julia. The line *does* *not* say that you can have Markdown inside docstrings. You are expecting people to imagine stuff. Blaming the user all the time is not going to lead to good documentation. I am giving you user feedback.

 

use markdown syntax inside docstrings

That is covered by the main Julia manual.

How so? How is that even possible? Are you telling me that Julia comes with a built-in Markdown processor? If that is the case, that is really news to me, and it makes me wonder what your module is contributing then. I thought you were providing a Markdown processor. And if you are not, doesn't that show that your documentation has failed at conveying what your module provides?

 

A link could be provided to that, but
generally the route potential users should be taking is to read the Julia
manual first and then go looking for packages that they need.

This is bad documentation design. And I have been reading Julia documentation for years. I have never heard of Julia having a built-in Markdown processor.

 

If I didn’t already know some Markdown

Yes, a link could be provided to resources that teach markdown. I’d be fine
with that, but Documenter’s manual is not the place to teach markdown syntax
from scratch.

It SHOULD teach the basics of Markdown. It should not teach *all* of Markdown, but if Markdown is at the core of what it does then it definitely needs to talk about it. If I was doing this, I would have a short section titled Markdown where I say that this module implements XYZ flavour of Markdown, show an example text (a heading, a sub-heading, a couple of lists, bold, italic, underlined -- just the basics) and then say "if you want to learn more about XYZ Markdown, to go this page".

I notice that in your email you still have not told me what flavour of Markdown you have implemented (or is it in Julia?). Is this also something that I am supposed to have inferred somehow?

 

Cheers,

Daniel.

[Michael Hatherly]

It honestly did not cross my mind that those pictures were links.

To me they shout click me, but I really do understand the issue you’re
highlighting Daniel. I’m busy updating the page to add some real links.
Thank you for pointing it out, much appreciated! I think we can safely
wrap up that part of the conversation.

Blaming the user all the time is not going to lead to good documentation. I am giving you user feedback.

That’s not my intention, apologies if that came across that way. I’ve simply
written the docs for the package with a set of assumptions in my mind about
what knowledge is already available elsewhere. I’ll definitely make use of your
feedback and improve/clarify the parts the need it. Thank you.

This is bad documentation design. And I have been reading Julia documentation for years. I have never heard of Julia having a built-in Markdown processor.

I’ll be adding a link to the relevant docs in the Julia manual. The markdown parser
has been part of Base since 0.4 was released and is mentioned in the Documentation
section of the manual. If things could be clearer in that section then please open
an issue or PR so that that can be fixed.

It SHOULD teach the basics of Markdown.

I believe that we are probably just going to disagree one this one. A link to
the relevant information is fine for something like this. I wouldn’t expect
every single thing that I read to begin from first principles. That’s just how
I prefer to read things, though that’s probably just a personal thing. I’d be
fine with a PR to add a basic syntax tutorial if you’d like.

what flavour of Markdown

That’s discussed in the main Julia docs.

---

If I’ve still not addressed things enough, could a ask you to open some issues
in the Documenter.jl repo please? A long email thread is the best place for
these kind of important issues to get lost in and never get resolved properly.
Even if it’s just a couple of one-liner issues that would make fixing these
much easier for me. Thanks.

Once again, thank you for taking the time to discuss this. I know your time,
just like my own, is limited and could be being spent on other things.

— Mike

​

[Kristoffer Carlsson]

My view is that the README was perfectly fine. What do people think that the image that says [docs - stable] is there for if not for clicking and being taking to the docs..? They also share the same form as all the other badges which are clickable to go to the coverage, testing status etc. 

I have used Documenter in a few of my packages and it was really simple to set up the whole thing since the documentation explains everything so clearly. There are also multiple other packages that uses Documenter that are linked from the documentation so you can just go and look how they did stuff if there are still questions. Also, this package is for users who are developing packages so assuming a decent amount of knowledge of general Julia stuff is in my view fair game.

Just wanted to add my feedback so that multiple inputs are heard.

[Michael Hatherly]

Thanks for the feedback Kristoffer. Glad you’ve found the package useful!

Re: assuming certain knowledge. I think that for a very new package
such as this it’s definitely alright to make a fair number of assumptions. Going
forward I’ll be looking to expand those bits that have, until now, been glossed over and
start to make things more beginner-friendly, to a certain extent.

— Mike