Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refactor of top-level doc/README.rst #2227

Merged
merged 0 commits into from Jul 11, 2014
Merged

Conversation

dpsanders
Copy link

  • Replaced doc/README.txt with doc/README.md and markdown-ified.
  • Rearranged for clarity, separating the config files from the subdirectory list.
  • Introduced separate build section and reordered in the correct order.

In my opinion, the screenshots (pyplots directory) have a dubious status; but in any case pyplots should be e.g. inside users, as should glossary. I am not sure if this will break something, so I haven't done these moves myself.

@dpsanders
Copy link
Author

This is my first-ever pull request (and my first decent-sized Markdown file!), so please let me have gentle constructive criticism!

I knew a negative amount about branches, git and pull requests before the SciPy2013 matplotlib sprint -- many thanks to all those who coaxed me along!

Starting small but hope to be onto bigger things soon...

@dpsanders
Copy link
Author

Just realised that I should have been working from a branch. Next time...

@dpsanders
Copy link
Author

How would people feel about renaming doc -> docs? Seems a bit more logical to me.

@dpsanders
Copy link
Author

When I run
python make.py html
I get

Extension error:
Could not import extension sphinxext.math_symbol_table (exception: No module named math_symbol_table)

This is the first time this has happened. What is going on?

@mdboom
Copy link
Member

mdboom commented Jul 18, 2013

Thanks for working on this. This is definitely a corner of the docs that has not seen a lot of love in a while.

I'm curious about the motivation to use Markdown. The file was originally in reStructuredText (as is all the other documentation), and I'd hate to add another markup language to the mix unless there is a good reason. Github understands and will display reStructuredText. Maybe just rename txt to rst so github can do its magic?

Aside from that syntactic issue, I think the reorganization is nice, but it might be easiest if I hold off on commenting on the details until after resolving the issue above.

The pyplot documentation is in API because it describes the functions and the programming interface. users is for narrative and tutorial-like documentation. I think it belongs in API, but I'm open to suggestions about how to make it easier to find, etc.

@NelleV
Copy link
Member

NelleV commented Jul 18, 2013

I'm 👍 on keeping restructure text.

@NelleV
Copy link
Member

NelleV commented Jul 18, 2013

In general, I also like have <79 caracters line.

@dpsanders
Copy link
Author

Hi, I see, I didn't realise that the .txt file was supposed to be .rst and that is why it didn't display well.
I used markdown because that's all anybody ever mentioned at SciPy and that's what is used in the IPython notebook.

Time to learn ReST then... :P Or learn to use markup language converters... Is pandoc the correct one?

@NelleV
Copy link
Member

NelleV commented Jul 18, 2013

@dpsanders rst is the markup language used in docstrings, by sphinx and pretty much everywhere else in the Python community. The IPython notebook is a bit the exception in the python community!

@dpsanders
Copy link
Author

GitHub also uses Markdown...

Any comments about the rewrite of the README? And the proposal for moving the subdirectories into users?

@NelleV
Copy link
Member

NelleV commented Jul 19, 2013

The naming doc for the folder containing the documentation is a python standard. Hence, I'm against renaming it todocs``.

I'm not sure I understand the logic behind moving the glossary folder to the users folder. They seem to target to rather different things.

I don't know about the pyplots folder: it seems to contain a bunch of images and python scripts. @mdboom do you know those files where put there ?
IMO, images should go in a folder name images and the python scripts in the examples, unless the python scripts generates the images (in which case I'm not sure why they were added to the git repository).

Building the ``matplotlib`` package
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Begin by building the ``matplotlib`` package, using the command
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Most of the people will read this file using less or a text editor, and not on github. To make this file a bit more readable, could you use the following syntax:

Begin by building the ``matplotlib`` package, using the command::

     python setup.py build

@NelleV
Copy link
Member

NelleV commented Jul 19, 2013

The content of the README file seems good to me and well organized. I'm just a bit worried about the formatting. People are not going to read this file by rendering it into html, hence I'd rather stick to quite light formatting (almost no links, less blank lines, etc).

@dpsanders
Copy link
Author

OK I see, no problem. Do you know which version of numpydoc is required?

- ``sphinxext`` -- ``sphinx`` extensions for
``matplotlib`` documentation

- ``mpl\_examples`` -- symbolic link to top-level ``examples`` directory, so that examples may be referenced from within documentation
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you please use the posix standard? mpl/_examples instead of mpl\_examples. Both will work on windows while the latter won't work on linux or mac os x.

@NelleV
Copy link
Member

NelleV commented Jul 19, 2013

I think we are almost there! Apart from my last comments on the path, I'm 👍 for merging.

@dpsanders
Copy link
Author

Those \ were not actually path separators... (They were there to escape the
underscore I guess? This came from the automatic pandoc conversion.) I have
removed them.

For me, it's ready to merge!

On Fri, Jul 19, 2013 at 9:02 AM, Varoquaux notifications@github.com wrote:

I think we are almost there! Apart from my last comments on the path, I'm [image:
👍] for merging.


Reply to this email directly or view it on GitHubhttps://github.com//pull/2227#issuecomment-21251082
.

Dr. David P. Sanders

Profesor Titular "A" / Associate Professor
Departamento de Física, Facultad de Ciencias
Universidad Nacional Autónoma de México (UNAM)

dpsanders@gmail.com
http://sistemas.fciencias.unam.mx/~dsanders

Cubículo / office: #414, 4o. piso del Depto. de Física

Tel.: +52 55 5622 4965

@dpsanders
Copy link
Author

Hold on, it is not rendering well in GitHub.

On Fri, Jul 19, 2013 at 9:05 AM, David P. Sanders dpsanders@gmail.comwrote:

Those \ were not actually path separators... (They were there to escape
the underscore I guess? This came from the automatic pandoc conversion.) I
have removed them.

For me, it's ready to merge!

On Fri, Jul 19, 2013 at 9:02 AM, Varoquaux notifications@github.comwrote:

I think we are almost there! Apart from my last comments on the path, I'm [image:
👍] for merging.


Reply to this email directly or view it on GitHubhttps://github.com//pull/2227#issuecomment-21251082
.

Dr. David P. Sanders

Profesor Titular "A" / Associate Professor
Departamento de Física, Facultad de Ciencias
Universidad Nacional Autónoma de México (UNAM)

dpsanders@gmail.com
http://sistemas.fciencias.unam.mx/~dsanders

Cubículo / office: #414, 4o. piso del Depto. de Física

Tel.: +52 55 5622 4965

Dr. David P. Sanders

Profesor Titular "A" / Associate Professor
Departamento de Física, Facultad de Ciencias
Universidad Nacional Autónoma de México (UNAM)

dpsanders@gmail.com
http://sistemas.fciencias.unam.mx/~dsanders

Cubículo / office: #414, 4o. piso del Depto. de Física

Tel.: +52 55 5622 4965

@dpsanders
Copy link
Author

Ready :)

On Fri, Jul 19, 2013 at 9:08 AM, David P. Sanders dpsanders@gmail.comwrote:

Hold on, it is not rendering well in GitHub.

On Fri, Jul 19, 2013 at 9:05 AM, David P. Sanders dpsanders@gmail.comwrote:

Those \ were not actually path separators... (They were there to escape
the underscore I guess? This came from the automatic pandoc conversion.) I
have removed them.

For me, it's ready to merge!

On Fri, Jul 19, 2013 at 9:02 AM, Varoquaux notifications@github.comwrote:

I think we are almost there! Apart from my last comments on the path,
I'm [image: 👍] for merging.


Reply to this email directly or view it on GitHubhttps://github.com//pull/2227#issuecomment-21251082
.

Dr. David P. Sanders

Profesor Titular "A" / Associate Professor
Departamento de Física, Facultad de Ciencias
Universidad Nacional Autónoma de México (UNAM)

dpsanders@gmail.com
http://sistemas.fciencias.unam.mx/~dsanders

Cubículo / office: #414, 4o. piso del Depto. de Física

Tel.: +52 55 5622 4965

Dr. David P. Sanders

Profesor Titular "A" / Associate Professor
Departamento de Física, Facultad de Ciencias
Universidad Nacional Autónoma de México (UNAM)

dpsanders@gmail.com
http://sistemas.fciencias.unam.mx/~dsanders

Cubículo / office: #414, 4o. piso del Depto. de Física

Tel.: +52 55 5622 4965

Dr. David P. Sanders

Profesor Titular "A" / Associate Professor
Departamento de Física, Facultad de Ciencias
Universidad Nacional Autónoma de México (UNAM)

dpsanders@gmail.com
http://sistemas.fciencias.unam.mx/~dsanders

Cubículo / office: #414, 4o. piso del Depto. de Física

Tel.: +52 55 5622 4965

@dpsanders
Copy link
Author

@NelleV You are correct that the Python scripts in pyplots should be in examples. This would be a separate PR.

@pelson
Copy link
Member

pelson commented Jan 14, 2014

@NelleV - I think we should either get this in v1.4.x or close the PR - this will go stale quickly if we can't get it in soon ish. Are you and @dpsanders in a position to take a look at what is needed to get this back up to speed?

@NelleV
Copy link
Member

NelleV commented Jan 14, 2014

On 14 January 2014 16:22, Phil Elson notifications@github.com wrote:

@NelleV https://github.com/NelleV - I think we should either get this
in v1.4.x or close the PR - this will go stale quickly if we can't get it
in soon ish. Are you and @dpsanders https://github.com/dpsanders in a
position to take a look at what is needed to get this back up to speed?

I've got a deadline, and I have been swamped with work. When is 1.4.x
supposed to come out?
I can try to have a look at this during the week-end.


Reply to this email directly or view it on GitHubhttps://github.com//pull/2227#issuecomment-32273221
.

@pelson
Copy link
Member

pelson commented Jan 14, 2014

I've got a deadline, and I have been swamped with work

Ok. Don't worry too much - if we can get it in we will, but otherwise it might have to be the other side of v1.4.x.

Best of luck with your deadline!

@dopplershift dopplershift merged commit 2d43258 into matplotlib:master Jul 11, 2014
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

6 participants