Pipeline docs are incomplete #220

Closed
larsmans opened this Issue Jun 24, 2011 · 15 comments

Projects

None yet

5 participants

@larsmans
Owner

I just noticed that the documentation for the Pipeline class doesn't properly show up in the generated HTML. I tried to fix it, but I can't get the example to show up properly. That's a shame since the lead paragraphs refer to it.

Owner

Hey Lars,

Thanks for having a look at this. The pipeline docs do need a lot of work.

I had a close look at the issue, and I didn't make much progress so far. Here are some of my findings:

  • Most of the different classes in the scikit have the same problem. In other words, this is a major issue.
  • There are some warnings that are spit out by the doc building system. They are really hard to see because the doc building system spits out too much warnings. This is another major issue. I spent a week end once cleaning out warnings. It looks that there is more work to be done in cleaning up warnings. We have really been slacking here: accepting code that spits out warning is not an issue. Maybe I should send an email on the mailing list :).
  • Finally, here are the warnings corresponding to the problem that you have uncovered:
/home/varoquau/dev/scikit-learn/scikits/learn/decomposition/pca.py:docstring of scikits.learn.decomposition.ProbabilisticPCA:89: (ERROR/3) Error in "autosummary" directive:
no arguments permitted; blank line required before content block.

.. autosummary::
   fit
   fit_transform
   inverse_transform
   score
   transform

/home/varoquau/dev/scikit-learn/doc/modules/generated/scikits.learn.decomposition.ProbabilisticPCA.rst:44: (ERROR/3) Unknown target name: "components".
/home/varoquau/dev/scikit-learn/scikits/learn/decomposition/pca.py:docstring of scikits.learn.decomposition.RandomizedPCA:67: (ERROR/3) Malformed table.
Column span alignment problem at line offset 5.

================================================    ==========
  components_: array, [n_components, n_features]    
                                                    Components with maximum variance.

explained_variance_ratio_: array, [n_components]    
                                                    Percentage of variance explained by each of the selected components.
                                                    k is not set then all components are stored and the sum of
                                                    explained variances is equal to 1.0
================================================    ==========
/home/varoquau/dev/scikit-learn/scikits/learn/decomposition/pca.py:docstring of scikits.learn.decomposition.RandomizedPCA:79: (ERROR/3) Error in "autosummary" directive:
no arguments permitted; blank line required before content block.

.. autosummary::
   fit
   fit_transform
   inverse_transform
   transform
Owner
fabianp commented Jun 25, 2011

I found the docstring generation in sphinx (or the numpy plugin) to be extremely fragile ... I wonder if we can do something about that.

Plus there are pages of warnings that I do not know how to deal with, although sphinx 1.0.5 seems to be giving better feedback than previous versions

Owner
fabianp commented Jun 25, 2011

I would mark cleaning the warnings from the doc generation as a goal for the 0.9 release, this has been around for too much time ...

Owner

I fixed one (l1_distances was renamed to manhattan_distances). I'll hunt down a few more over the coming week.

A quick question - it looks like some errors are happening because the syntax for headings (many '-' under a string) is used for tables in examples. What would be the best way of dealing with this?
e.g.:

/home/bob/Code/scikit-learn/doc/auto_examples/cluster/plot_kmeans_digits.rst:45: (SEVERE/4) Unexpected section title.

PCA-based   0.10s    71820   0.673   0.715   0.693   0.567   0.670    0.150
_______________________________________________________________________________

Owner

A quick question - it looks like some errors are happening because the syntax for headings (many '-' under a string) is used for tables in examples. What would be the best way of dealing with this?
e.g.:

/home/bob/Code/scikit-learn/doc/auto_examples/cluster/plot_kmeans_digits.rst:45: (SEVERE/4) Unexpected section title.

PCA-based   0.10s    71820   0.673   0.715   0.693   0.567   0.670    0.150
_______________________________________________________________________________

Are you sure that this still happens with the latest code: I thought that
I had fixed this problem.

G

Owner

It has been fixed. I did do a merge at home (where I was when I last posted). This doesn't happen on my work computer.

... also, the warnings are hard to read... is there any way to put them in a log format or another readable format?

Owner

On Mon, Nov 14, 2011 at 04:22:36PM -0800, Robert Layton wrote:

... also, the warnings are hard to read... is there any way to put them in a log format or another readable format?

I don't know, but I agree with your statement.

G

Owner
amueller commented Jan 6, 2012

@robertlayton @GaelVaroquaux The best way to read the errors in my experience is pipe to a file and read without line wrapping. Actually the line wrapping is what really messes it up.

It could be improved by not printing the whole file as a list of strings, but I guess this would be hard as the rst code is generated. It would be ideal to get the line in the file from which the code was generated... I think this is a sphinx autodoc issue.

Owner
amueller commented Jan 6, 2012

I think this issue can be closed, as the pipeline docs do show up now.
Also, there are not that many errors in the doc building left ;)

Owner
larsmans commented Jan 6, 2012

The Attributes section still doesn't show up, nor does the Example. I've updated the link in the issue description to point to http://scikit-learn.org/dev/modules/generated/sklearn.pipeline.Pipeline.html.

Owner
amueller commented Jan 6, 2012

They do in the current version. It's just not on the website, yet. Or doesn't it work for you?

Owner
larsmans commented Jan 6, 2012

Ok. I don't have time to go through the entire doc building process right now, so I'll just take your word for it.

@larsmans larsmans closed this Jan 6, 2012
Owner
amueller commented Jan 6, 2012

Does building the docs take so much time for you (without the figures)?
I think on my old laptop it takes about 5 minutes.

Owner
larsmans commented Jan 6, 2012

It's just that I'm really working right now :)

Owner
amueller commented Jan 6, 2012

Fair enought. I'm procrastinating as you can see ;)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment