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
Conversation
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... |
Just realised that I should have been working from a branch. Next time... |
How would people feel about renaming doc -> docs? Seems a bit more logical to me. |
When I run Extension error: This is the first time this has happened. What is going on? |
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 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. |
I'm 👍 on keeping restructure text. |
In general, I also like have <79 caracters line. |
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. Time to learn ReST then... :P Or learn to use markup language converters... Is pandoc the correct one? |
@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! |
GitHub also uses Markdown... Any comments about the rewrite of the README? And the proposal for moving the subdirectories into users? |
The naming I'm not sure I understand the logic behind moving the I don't know about the |
Building the ``matplotlib`` package | ||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
Begin by building the ``matplotlib`` package, using the command |
There was a problem hiding this comment.
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
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). |
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 |
There was a problem hiding this comment.
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.
I think we are almost there! Apart from my last comments on the path, I'm 👍 for merging. |
Those \ were not actually path separators... (They were there to escape the For me, it's ready to merge! On Fri, Jul 19, 2013 at 9:02 AM, Varoquaux notifications@github.com wrote:
Dr. David P. Sanders Profesor Titular "A" / Associate Professor dpsanders@gmail.com Cubículo / office: #414, 4o. piso del Depto. de Física Tel.: +52 55 5622 4965 |
Hold on, it is not rendering well in GitHub. On Fri, Jul 19, 2013 at 9:05 AM, David P. Sanders dpsanders@gmail.comwrote:
Dr. David P. Sanders Profesor Titular "A" / Associate Professor dpsanders@gmail.com Cubículo / office: #414, 4o. piso del Depto. de Física Tel.: +52 55 5622 4965 |
Ready :) On Fri, Jul 19, 2013 at 9:08 AM, David P. Sanders dpsanders@gmail.comwrote:
Dr. David P. Sanders Profesor Titular "A" / Associate Professor dpsanders@gmail.com Cubículo / office: #414, 4o. piso del Depto. de Física Tel.: +52 55 5622 4965 |
@NelleV You are correct that the Python scripts in pyplots should be in examples. This would be a separate PR. |
@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? |
On 14 January 2014 16:22, Phil Elson notifications@github.com wrote:
I've got a deadline, and I have been swamped with work. When is 1.4.x
|
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! |
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.