Blog-post on how to make package documentation

[Mauro]

Until a few days ago, I was a bit confused on how to go about writing
nice package documentation, including API-docs. I figured it out and it
turned out to be pretty trivial, once I knew how. I wrote it up in case
someone else is confused (or I become confused again):
http://maurow.bitbucket.org/notes/documenting-a-julia-package.html
(feedback welcome)

Mauro

[Tom Breloff]

Thanks for this Mauro... I bookmarked the page, as I'm sure I'll come back to reference it many times.

[Michael Hatherly]

Thanks for writing that up Mauro and also the shout-out :) Worth noting Mike Innes' important work in getting the docsystem integrated into `Base` and his

heroic effort converting most of the docs from rst to markdown as well.

On a technical note, Lexicon doesn't actually use the docsystem in `Base` at all and still relies on Docile's own implementation currently, so it's possible

that people may start to run into problems with this approach on 0.5 as it further diverges from 0.3/0.4. (Do open issues if they happen to crop up

though and I'll do my best to keep things working as long as possible.) Future work using the `Base` docsystem for documentation generation is moving

ahead, when time allows, in a separate package, https://github.com/MichaelHatherly/Lapidary.jl.

-- Mike

[Mauro]

Mike and Tom, thanks! And yes, the other Mike needs mentioning too, I
updated that footnote.

[Mauro]

Actually, Mike, is there a way to sort the API docs? Alphabetical or to
some given order?

On Wed, 2016-02-17 at 17:44, Michael Hatherly <michael...@gmail.com> wrote:

[Cedric St-Jean]

Thank you for this.

Has anyone evaluated using Sphinx instead? JuMP uses it, and it may fit my needs better, but it's hard to tell.

[Miles Lubin]

FYI we're planning on moving JuMP away from Sphinx and ReadTheDocs for various reasons.

[Cedric St-Jean]

What are you replacing Sphinx with?