How do you keep documentation so nice?

[Adam Hughes]

Hi,

I've been working with sphinx api-doc for autogenerating some documentation for a package, and the output is a farcry from the nice, super-slick layout that scikit-image has.  I saw that on the bottom of your page, the docs are built with sphinx and bootstrap.  Is the source code for the documentation available for perusing by chance?  I'd love to get some insights on how you keep your page so nice and tidy!

[Adam Hughes]

I'm dumb.  It's clearly right there on your github page in "docs".  Geez.

It's ok if I draw inspiration from you guys, right? 

On Sun, Dec 7, 2014 at 7:11 PM, Adam Hughes <hughes...@gmail.com> wrote:

Hi,

I've been working with sphinx api-doc for autogenerating some documentation for a package, and the output is a farcry from the nice, super-slick layout that scikit-image has.  I saw that on the bottom of your page, the docs are built with sphinx and bootstrap.  Is the source code for the documentation available for perusing by chance?  I'd love to get some insights on how you keep your page so nice and tidy!

--
You received this message because you are subscribed to a topic in the Google Groups "scikit-image" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/scikit-image/k5K6_vanZVI/unsubscribe.
To unsubscribe from this group and all its topics, send an email to scikit-image...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Juan Nunez-Iglesias]

Hahaha it's not that dumb! I personally have tried to dive into the doc build process a few times but have found it quite opaque, so I wouldn't mind if Stéfan and/or Tony elaborated a bit here about the build system! =)

But as to drawing inspiration, I'm pretty sure it's all BSD, which means you can draw even a bit more than that! =)

You received this message because you are subscribed to the Google Groups "scikit-image" group.
To unsubscribe from this group and stop receiving emails from it, send an email to scikit-image...@googlegroups.com.

[Adam Hughes]

Thanks Juan.  It's funny, but I feel like writing documents is 10 times harder than writing software

[Adam Hughes]

I really am impressed by this plt2rst.py module for autogenerating example documentation!

I've been trying to implement it just to test it out and think I have it setup right in terms of placement in my docs directory, I made an example plot_test.py file in examples, but I'm confused on how to actually use the plt2rst.py module.  Consider this line from that file:

    def setup(app):

        app.connect('builder-inited', generate_example_galleries)

        app.add_config_value('plot2rst_paths',

                         ('../examples', 'auto_examples'), True

When/how is this ever called?  The examples themselves don't use these directives; so when is this found?

When I build in my make file, no auto_examples.html file is ever created in my build directory.  So I'm thinking I'm not using this correctly.  Is there another step besides just doing make build?  

[Tony Yu]

Hi Adam!

On Mon, Dec 8, 2014 at 5:40 PM, Adam Hughes <hughes...@gmail.com> wrote:

I really am impressed by this plt2rst.py module for autogenerating example documentation!

I've been trying to implement it just to test it out and think I have it setup right in terms of placement in my docs directory, I made an example plot_test.py file in examples, but I'm confused on how to actually use the plt2rst.py module.  Consider this line from that file:

    def setup(app):

        app.connect('builder-inited', generate_example_galleries)

        app.add_config_value('plot2rst_paths',

                         ('../examples', 'auto_examples'), True

When/how is this ever called?  The examples themselves don't use these directives; so when is this found?

This plotting code is partially my fault, so I'll try to explain based on memory. I should say, though, that I adapted this code from an older version in the `scikit-image` docs, which took it from `scikit-learn` (which may have taken it from nipy or some other project). That is to say, I don't completely understand all the things. ;)

This particular `setup(app)` function is run as part of the Sphinx infrastructure (see http://sphinx-doc.org/extdev/tutorial.html).

 

When I build in my make file, no auto_examples.html file is ever created in my build directory.  So I'm thinking I'm not using this correctly.  Is there another step besides just doing make build?  

There's a bit of documentation written up here:

https://github.com/tonysyu/mpltools/blob/master/doc/source/getting_started.rst#plot2rst-sphinx-extension

One possible hang-up is that examples are expected to start with `plot_` and an `index.rst` file is required in gallery directories.

I haven't looked at this in a while, but if you have any more questions, I can try to dig into the code a bit to try to remember what's going on.

Cheers!

-Tony

[Stefan van der Walt]

Hi Adam

On 2014-12-09 04:12:17, Tony Yu <tsy...@gmail.com> wrote:
>> I really am impressed by this plt2rst.py module for autogenerating example
>> documentation!

Also have a look at this project, which tries to unify the gallery
builders of the different projects:

https://github.com/sphinx-gallery/sphinx-gallery

Stéfan

[Adam Hughes]

Thanks Tony and Stefan for the resources, I will start working on them now.

[Adam Hughes]

PS,

Tony, I don't see an index.rst file in scikit-images gallery.  You're talking about this folder, yes?:

https://github.com/scikit-image/scikit-image/tree/master/doc/examples

[Adam Hughes]

Nevermind guys, I was able to get it working through that sphinx-gallery link that Stefan set.  Thanks for all of your help!  Really feels great to see how nice a website can be created from just auto-docs.

[Stefan van der Walt]

Hi Adam

On 2014-12-09 22:54:34, Adam Hughes <hughes...@gmail.com> wrote:
> Nevermind guys, I was able to get it working through that sphinx-gallery
> link that Stefan set.

I'm not sure how--that repo still looks to be fairly empty!

The process is: we run tools that generates .rst files, the rst files
get compiled by Sphinx, during which the plots etc. get generated. The
result is then pushed to a repository on GitHub. Easiest way to
understand it is to run the script and examine the new files created.

Stéfan

[Juan Nunez-Iglesias]

Stéfan,

> I'm not sure how--that repo still looks to be fairly empty!

Huh??? You sent that link! LOL I was puzzled too but then saw the PR from the owner's "personal" fork of the repo, which I guess (no time to look at it yet) has a fair few resources.

> the rst files get compiled by Sphinx, during which the plots etc. get generated.

I don't actually understand the process of generating plots in the case of hand-written docs. E.g. this image embed by Emmanuelle:

https://github.com/scikit-image/scikit-image/blob/master/doc/source/user_guide/numpy_images.txt#L73

Is that generated from the code in the .rst file itself, or does she have to know (through non-automated means) that the auto-example produces the same image as is required in the rst?

Juan.

[Stefan van der Walt]

Hi Juan

On 2014-12-10 00:59:01, Juan Nunez-Iglesias <jni....@gmail.com> wrote:
> Huh??? You sent that link! LOL I was puzzled too but then saw the PR
> from the owner's "personal" fork of the repo, which I guess (no time
> to look at it yet) has a fair few resources.

This is where the project is supposed to be maintained--I am following
the discussions, and thought they just haven't committed any code. Now
that I know differently I'll ask them to commit to that branch.

> I don't actually understand the process of generating plots in the case of hand-written docs. E.g. this image embed by Emmanuelle:
>
> https://github.com/scikit-image/scikit-image/blob/master/doc/source/user_guide/numpy_images.txt#L73

She "cheated" a bit and included an image from the gallery.

> Is that generated from the code in the .rst file itself, or does she
> have to know (through non-automated means) that the auto-example
> produces the same image as is required in the rst?

In this case, yes.

Stéfan

[Juan Nunez-Iglesias]

Thanks for all that. =)

> She "cheated" a bit and included an image from the gallery.

If I want to include my own non-gallery image, should I generate it manually, and if so, where should I put it?

[Stefan van der Walt]

On 2014-12-10 01:46:40, Juan Nunez-Iglesias <jni....@gmail.com> wrote:
> If I want to include my own non-gallery image, should I generate it
> manually, and if so, where should I put it?

In that case, you can use the "plot" directive (see `plot_directive.py`
in the `doc/ext` directory. Sorry that you have to pry all of this out
of me--I am also rusty since I don't use it that often.

Stéfan

[Adam Hughes]

Hey guys,

Thanks for all of your help!  Here is my working version:

http://hugadams.github.io/scikit-spectra/

Check out the IPython GUI video if you're interested.

[Stefan van der Walt]

Hi Adam

On 2014-12-10 02:43:46, Adam Hughes <hughes...@gmail.com> wrote:
> http://hugadams.github.io/scikit-spectra/

That is a very impressive notebook widget shown in the video! I love
how it interacts with mpl3d.

Stéfan

[Adam Hughes]

Thanks Stefan.  Ya we were pretty surprised when dumping the mpld3 html back into midel just happened to work and not break anything

[Adam Hughes]

*model

[Michael Aye]

On 2014-12-10 02:43:46, Adam Hughes <hughes...@gmail.com> wrote:

> http://hugadams.github.io/scikit-spectra/

That is a very impressive notebook widget shown in the video!  I love
how it interacts with mpl3d.

Ditto! Man, can't wait to play with this! Very happy that there's finally a package focusing on spectral analysis! It also just comes at the right time, just started in my new job working on data from an imaging spectrometer for the first time. ;)

Michael
 

[Adam Hughes]

Thanks Michael.

Be warned, only about 3 people are using the library at the moment, so it's quite likely that you'll encounter some bugs just by virtue of using a new dataset that probably will bring to light some considerations that we overlooked.  In addition, I only support pandas 0.14 right now (0.15 has a lot of private API changes that directly affect us).  But we did feel like the library was close enough to ready to share it, and I hope you can try it out.  If you do want to give it a whirl sometime soon, please feel free to contact us at sks...@googlegroups.com (or me personally) and we will at least make sure to help get you up and running.  Let us know what kind of data you're working on and what type of analysis you're doing.  We've spend a lot of time putting out datastructures together, but we haven't put a great deal of thought into the actual spectral utilitiles, workflows and analysis that we should host, other than correlation spectroscopy and base things like dynamic baseline fitting.

--

[Juan Nunez-Iglesias]

Adam, just fyi, we are considering moving away from GoogleGroups... (See a separate discussion on this list). Since you are on the ground floor, you might want to reconsider your choice. I've been using Nabble for my (very low volume!) gala list and it's been really good.

You received this message because you are subscribed to the Google Groups "scikit-image" group.

To unsubscribe from this group and stop receiving emails from it, send an email to scikit-image...@googlegroups.com.

[Adam Hughes]

Thanks, that's great advice.  Also, do you guys pay to host your site?  Can you recommend a low-cost, or free, static-website hosting vendor?  We are currently using gh-pages branch on github to host our site, and I really hate having this secondary branch.  Especially when I need the documentation to have access to the source code modules or setup.py file (as it's on a second branch).

[Thomas Caswell]

matplotlib uses the organization-level gh-pages to host the documentation which seems to work pretty well.

[Stéfan van der Walt]

On Dec 11, 2014 7:58 PM, "Thomas Caswell" <tcas...@gmail.com> wrote:
>
> matplotlib uses the organization-level gh-pages to host the documentation which seems to work pretty well.

We do the same thing, in fact.  No go-pages branch needed.

Stéfan

[Adam Hughes]

Wait, so github is hosting scikitimage.org?

To my (outdated) understanding, one had to use a gh-pages branch for github to find the documentations.  If I were to put the docs in the package master branch as you've done, how can github find a hook to host the site?

--

[Stefan van der Walt]

Hi Adam

On 2014-12-12 19:46:55, Adam Hughes <hughes...@gmail.com> wrote:
> Wait, so github is hosting scikitimage.org?
>
> To my (outdated) understanding, one had to use a gh-pages branch for github
> to find the documentations. If I were to put the docs in the package
> master branch as you've done, how can github find a hook to host the site?

If you name the repository orgname.github.io, then you can push into the
master branch, IIRC.

Regards
Stéfan

[Adam Hughes]

Hey Thomas,

Sorry for late reply.  Can you expand on this a little bit?  Benjamin Root said to ask you about how the docs work.  Essentially, how do you host them on the master branch under the docs folder and still have them hosted at matplotlib.org?  Instead of hosting them on gh-pages and having them show up as github.com/matplotlib?   I'm having the hardest time finding info on this.