Skip to content

DOC: add missing docs - #12250

Merged
rgommers merged 5 commits into
numpy:masterfrom
mattip:add-docs-to-toc
Nov 5, 2018
Merged

rgommers merged 5 commits into
numpy:masterfrom
mattip:add-docs-to-toc

Conversation

@mattip

@mattip mattip commented Oct 23, 2018 •

Copy link
Copy Markdown
Member

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
Copy Markdown
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?

Comment thread doc/source/dev/index.rst Outdated
:maxdepth: 3

conduct/code_of_conduct
conduct/report_handling_manual

Copy link
Copy Markdown
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
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Removed

.. toctree::

internals.code-explanations
alignment

Copy link
Copy Markdown
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
Copy Markdown
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

mattip commented Oct 25, 2018

Copy link
Copy Markdown
Member Author

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

mattip commented Oct 25, 2018

Copy link
Copy Markdown
Member Author

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

@mattip

mattip commented Oct 25, 2018

Copy link
Copy Markdown
Member Author

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

Moved to dev section

@mattip

mattip commented Nov 4, 2018

Copy link
Copy Markdown
Member Author

@rgommers ping

@rgommers
rgommers merged commit bc81177 into numpy:master Nov 5, 2018
@rgommers

rgommers commented Nov 5, 2018

Copy link
Copy Markdown
Member

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