8000 DOC: add missing docs by mattip · Pull Request #12250 · numpy/numpy · GitHub
[go: up one dir, main page]

Skip to content

DOC: add missing docs #12250

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

Merged
merged 5 commits into from
Nov 5, 2018
Merged

DOC: add missing docs #12250

merged 5 commits into from
Nov 5, 2018

Conversation

mattip
Copy link
Member
@mattip mattip commented Oct 23, 2018

Some of the top-level *.rst.txt docs were not part of our on-line or PDF docs:

  • DISTUTILS.rst.txt
  • C_STYLE_GUIDE.rst.txt

Additionally, the conduct/report_handling_manual.rst and alignment.rst documents were not linked into a TOC, thus unavailable via links.

The top level CAPI.rst.txt is not linked in, I think we can drop or move it to informational NEPS if it has historical relevance still.

Edit: "orphaned" dos that are not in a TOC

@rgommers
Copy link
Member

Good idea to clean this up. A few comments:

  • It looks to me like the distutils guide should go into the user guide, not the reference docs.
  • C style guide should either become a NEP or be part of the dev guide, not the reference docs.
  • The distutils section could also use a few simple cleanups, it's clear now that it was written 10 years ago: change references to "SciPy" to general scientific packages, edit the "useful functions ..." section and turn things into links there.

Additionally, the conduct/report_handling_manual.rst and alignment.rst documents were not linked into a TOC, thus unavailable via links.

That's not quite how it works, e.g. the report_handling page is linked from https://www.numpy.org/devdocs/dev/conduct/code_of_conduct.html#incident-reporting-resolution-code-of-conduct-enforcement. I'll comment on these changes separately.

The top level CAPI.rst.txt is not linked in, I think we can drop or move it to informational NEPS if it has historical relevance still.

That sounds right. Would be good to verify that all content is already present in the docs - did you do that?

@@ -6,6 +6,7 @@ Contributing to NumPy
:maxdepth: 3

conduct/code_of_conduct
conduct/report_handling_manual
Copy link
Member

Choose a reason for hiding this comment

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

This should be removed again. It's not something that should be visible under "Contributing to NumPy" (the main page of the dev guide). The page is linked already from the CoC itself.

Copy link
Member Author

Choose a reason for hiding this comment

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

Removed

@@ -5,5 +5,6 @@ NumPy internals
.. toctree::

internals.code-explanations
alignment
Copy link
Member

Choose a reason for hiding this comment

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

this looks good to add. the section headers need an edit though, I propose:

Copy link
Member Author

Choose a reason for hiding this comment

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

Done

@rgommers rgommers self-requested a review October 23, 2018 15:27
@mattip
Copy link
Member Author
mattip commented Oct 25, 2018

I broke these::

- It looks to me like the distutils guide should 
  go into the user guide, not the reference docs.
- C style guide should either become a NEP or be 
  part of the dev guide, not the reference docs.
- The distutils section could also use a few simple
  cleanups, it's clear now that it was written 10 years ago: 
  - change references to "SciPy" to general scientific packages
  - edit the "useful functions ..." section and turn things into links there.

out into a separate issue #12261

@mattip
Copy link
Member Author
mattip commented Oct 25, 2018

Changesets aeefb51 and 00e8e16 refactored and removed the outdated CAPI.rst.txt, after merging relevant information back into the docs

@mattip
Copy link
Member Author
mattip commented Oct 25, 2018

C style guide should either become a NEP or be part of the dev guide, not the reference docs.

Moved to dev section

@mattip
Copy link
Member Author
mattip commented Nov 4, 2018

@rgommers ping

@rgommers rgommers merged commit bc81177 into numpy:master Nov 5, 2018
@rgommers
Copy link
Member
rgommers commented Nov 5, 2018

Okay, in it goes. Thanks @mattip

@mattip mattip deleted the add-docs-to-toc branch March 4, 2019 13:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants
0