DOC: Linguistic edit to CONTRIBUTING.md #11469
Conversation
| where you could start out. | ||
|
|
||
| Or maybe through using *pandas* you have an idea of you own or are | ||
| looking for something in the documentation and thinking 'this can be | ||
| improved'...you can do something about it! | ||
|
|
||
| Feel free to ask questions on [mailing | ||
| list](https://groups.google.com/forum/?fromgroups#!forum/pydata) | ||
| Feel free to ask questions on the [mailing list](https://groups.google.com/forum/?fromgroups#!forum/pydata) |
There was a problem hiding this comment.
can you add a refernce to gitter as well, link is on the readme
|
Now added. |
|
cool, pls squash and ping when ready |
|
Wait a moment, I think the CONTRIBUTING.md file is autogenerated, and the actual source is @aechase this is a bit inconvenient, but could you redo the changes there? |
|
Maybe we should also add a comment to |
|
Ah no problem. Perhaps the note about |
|
Yes certainly OK to also mention it somewhere in contributing.rst itself |
|
@jorisvandenbossche @jreback I notice that EDIT: sorry, my branch wasn't synced to the master. HTML and |
|
For the html pages, the link you give if of the latest stable release, so there can be differences. Better look at http://pandas-docs.github.io/pandas-docs-travis/contributing.html which is built for each commit to master. There can be a deviation between the md and rst file, but that should only be because the md was not regenerated for the last changes to the rst file (this is a manual action). Conlcusion: you should look at the rst file (and updating the md file by autogenerating it from the latest rst file is always welcome) |
|
@jreback I think this is ready |
|
did you see the comment above? this needs to be edited in |
|
@jreback both are adapted, so I think this is good |
| in the Scientific Python community. This standard specifies the format of | ||
| the different sections of the docstring. See `this document | ||
| <https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_ | ||
| for a detailed explanation, or look at some of the existing functions to | ||
| extend it in a similar manner. | ||
|
|
||
| - The ``.rst`` files are used to automatically generate Markdown and HTML versions | ||
| of the docs. Therefore, please contribute to the docs only by editing the ``.rst`` | ||
| files, and not the ``.md`` files. |
There was a problem hiding this comment.
I think this is a bit too general, as the conversion to md files is only the case for contributing.rst/CONTRIBUTING.md
There was a problem hiding this comment.
@jorisvandenbossche for README.md and RELEASE.md as well though, right?
There was a problem hiding this comment.
Those are separate and not linked yet (RELEASE.md is only a small note, and README.md is being maintained as it's own file for now)
There was a problem hiding this comment.
Gotcha. How about:
- The
.rstfiles are used to automatically generate Markdown and HTML versions
of the docs. For this reason, please do not editCONTRIBUTING.mddirectly, but
instead make any changes todoc/source/contributing.rst.
We could also maybe add a sentence there mentioning pandoc?
There was a problem hiding this comment.
even better, paste in the command to actually generate them (its on the wiki now)
There was a problem hiding this comment.
There was a problem hiding this comment.
though i think this should just be a script
doc/regenerate_markdown_docs.sh then makes this pretty easy
|
@aechase sorry, didn't see the other file. ok then! ping when you have addressed @jorisvandenbossche comment. |
|
@jreback @jorisvandenbossche I agree, there ought to be a script for regenerating the Markdown files, but I don't have time to write it today. Happy with these changes? |
| Feel free to ask questions on `mailing list | ||
| <https://groups.google.com/forum/?fromgroups#!forum/pydata>`_ | ||
| Feel free to ask questions on the `mailing list | ||
| <https://groups.google.com/forum/?fromgroups#!forum/pydata>`_ or on `Gitter |
There was a problem hiding this comment.
iirc these have 2 have 2 trailing underscores @jorisvandenbossche
There was a problem hiding this comment.
Well, I think the 1 trailing underscore is OK in practice (it's also what sphinx says to use: http://sphinx-doc.org/rest.html#external-links), although in theory, if you don't want to reference this link again (eg with ``mailing list_), you should use two trailing underscores (http://stackoverflow.com/questions/27420317/restructured-text-rst-http-links-underscore-vs-use)
|
Just doing a final check. Where should the following links point?
I assume that once upon a time these were links to another section of the document, because the next line refers to |
|
these should link to a subsection in install.rst |
|
@jreback @jorisvandenbossche latest edit now up. Because I used a fresh install of pandoc on this one, the Markdown is showing up as highly edited. You might find the rich diff makes it more clear to see what's actually changed in the This edit also fixes the issue #11542. |
|
Looks good! @aechase this is ready to be merged on your part? Thanks a lot for this text editing! |
|
@jorisvandenbossche I'm happy if you're happy! |
|
And I am happy :-) |
| The ``.rst`` files are used to automatically generate Markdown and HTML versions | ||
| of the docs. For this reason, please do not edit ``CONTRIBUTING.md`` directly, | ||
| but instead make any changes to ``doc/source/contributing.rst``. Then, to | ||
| generate ``CONTRIBUTING.md``, use `pandoc<http://johnmacfarlane.net/pandoc/>`_ |
There was a problem hiding this comment.
although, not yet fully :-)
There is a space missing after pandoc here
There was a problem hiding this comment.
Fixed! Didn't push a new CONTRIBUTING.md because the space gets eaten by the conversion anyway.
Thorough edit of contributing.rst, and then generated a new Markdown file.
DOC: Linguistic edit to CONTRIBUTING.md
|
Merging! |
|
Awesome, now to stop procrastinating on my PR that actually requires coding... |
Also fixed a dead link to the Nose testing docs.