Blog-post on how to make package documentation

336 views
Skip to first unread message

Mauro

unread,
Feb 17, 2016, 10:13:38 AM2/17/16
to julia-users
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

unread,
Feb 17, 2016, 10:58:07 AM2/17/16
to julia-users
Thanks for this Mauro... I bookmarked the page, as I'm sure I'll come back to reference it many times.

Michael Hatherly

unread,
Feb 17, 2016, 11:44:50 AM2/17/16
to julia-users
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

unread,
Feb 17, 2016, 4:06:08 PM2/17/16
to julia...@googlegroups.com
Mike and Tom, thanks! And yes, the other Mike needs mentioning too, I
updated that footnote.

Mauro

unread,
Feb 17, 2016, 5:01:51 PM2/17/16
to julia...@googlegroups.com
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

unread,
Feb 29, 2016, 2:56:23 PM2/29/16
to julia-users
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

unread,
Feb 29, 2016, 3:26:15 PM2/29/16
to julia-users
FYI we're planning on moving JuMP away from Sphinx and ReadTheDocs for various reasons.

Cedric St-Jean

unread,
Feb 29, 2016, 3:50:15 PM2/29/16
to julia-users
What are you replacing Sphinx with?
Reply all
Reply to author
Forward
0 new messages