DOC: Documentation fixes

[madphysicist]

Typo fixes and text wrappings. More to come as I keep reading the docs.

[charris]

This doesn't render correctly. You can put single backticks around the whole expression, possibly with a :code: preceding, e.g.

       How many bytes needed to jump from the end of a dimension back
       to its beginning. Note that :code:`backstrides[k]= strides[k] *
       dims_m1[k]`, but it is stored here as an optimization.

You can check things by changing to the doc directory, doing make html and then viewing build/html/index.html in a browser.

[njsmith]

Note also for future reference that bare single backticks are basically never right in vanilla Sphinx. They assign some text the "default role". If a particular build has been configured to set this to something useful, and you know what that is and it's local convention to use it, then great, but otherwise it's better to be explicit :-). (This is definitely the most annoying incompatibility between markdown and rst.)

[madphysicist]

Updated all the k-ths and the broken code block. Thanks for letting me know about how to view the docs. My knowledge of sphinx had been purely based on reading the docs and making changes by ear to things that were obviously not showing up correctly.

I made two additional changes:

• Added _static folder with empty .gitignore to doc/source to remove sphinx warning.
• Added AllOnes to doc/source/reference/c-api.types-and-structures.rst as a followup to ENH: Add bitwise_and identity #7373

[charris]

What was the warning about _static folder?

[madphysicist]

That it was missing:

copying static files... WARNING: html_static_path entry '.../numpy/doc/source/_static' does not exist

[madphysicist]

A better solution might be to create the path in the makefile or in the sphinx setup file. Or better yet, just suppress the warning since it seems like the folder is totally unnecessary in source.

[charris]

I suppose there is a possible use of the _static file, although I am not clear on what it is for.

[madphysicist]

The _static folder is for customizing the CSS and common images on the site. If the folder is not present in source, sphinx generates the default content to build/_static.

[charris]

This is an actual code change. What is the reason here (and below)?

[charris]

I'd rather the histogram changes were in a separate PR.

[madphysicist]

They are (#7416). This is a big mistake on my part. Got careless with Git.

[charris]

I notice that the doc/build/html/_static folder is not empty. If we add the folder will the contents still be generated?

[madphysicist]

Yes. I reran make html and everything is fine, including the contents of build/html/_static. The .gitignore file I added does not interfere with anything.

[madphysicist]

Removed the histogram stuff.

[madphysicist]

To be more specific:

Running (from doc)

rm -rf source/_static
make html
cp -r build/html/_static ~/static1

And then

make clean
git checkout source/_static/.gitignore # Using git in this case to restore the
                                       # two lines of comment in the gitignore file
make html
cp -r build/html/_static ~/static2

Yields the exact same contents for both folders via diff -r ~/static*. The .gitignore file is not copied over. It just makes it possible to add the missing folder to git so that the warning goes away.

[charris]

Thanks @madphysicist .