Skip to content
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.

Sign up for GitHub

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

Jump to bottom

developer contributing docs - llvm, sqlite3, sphinx-rtd-theme, and make html #7367

Closed
wants to merge 10 commits into from
Closed

developer contributing docs - llvm, sqlite3, sphinx-rtd-theme, and make html #7367

Changes from 6 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
c727f0c
add numba/label/ci_llvmlite_0.38 as channel and note about Windows sq…
sgbaird Sep 4, 2021
ad41a7b
install rtd theme and note that build occurs under docs/ folder
sgbaird Sep 4, 2021
75da906
proper indentation
sgbaird Sep 4, 2021
363d9e8
change channel to numba/label/dev per esc comment
sgbaird Sep 4, 2021
51dba44
hyperlink had space
sgbaird Sep 4, 2021
6e979d2
Merge branch 'dev-docs' of https://github.com/sparks-baird/numba into…
sgbaird Sep 4, 2021
f4a67ef
change pip to conda install
sgbaird Nov 4, 2021
9431bf3
remove reference about using pre-commit hooks on Windows
sgbaird Feb 2, 2022
3f408db
remove reference to bootstrap theme
sgbaird Feb 2, 2022
59e6da1
Update docs/source/developer/contributing.rst
sgbaird Mar 9, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
18 changes: 12 additions & 6 deletions docs/source/developer/contributing.rst
View file
Open in desktop
Expand Up @@ -91,10 +91,11 @@ recommend you use `conda <http://conda.pydata.org/miniconda.html>`_ to
create a dedicated development environment and install precompiled versions
of those dependencies there.

First add the Anaconda Cloud ``numba`` channel so as to get development builds
of the llvmlite library::
First add the Anaconda Cloud ``numba`` and ``numba/label/dev``
channels so as to get development builds of the llvmlite library::

$ conda config --add channels numba
$ conda config --add channels numba/label/dev

Then create an environment with the right dependencies::

Expand All @@ -118,7 +119,7 @@ Once the environment is activated, you have a dedicated Python with the
required dependencies::

$ python
Python 3.8.5 (default, Sep 4 2020, 07:30:14)
Python 3.8.5 (default, Sep 4 2020, 07:30:14)
[GCC 7.3.0] :: Anaconda, Inc. on linux
Type "help", "copyright", "credits" or "license" for more information.

Expand Down Expand Up @@ -260,6 +261,11 @@ and then running::
from the root of the Numba repository. Now ``flake8`` will be run each time
you commit changes. You can skip this check with ``git commit --no-verify``.

.. note::
To use these pre-commit hooks on Windows, it may be necessary to copy
``sqlite3.dll`` from ``C:\Users\<USER>\anaconda3\Library\bin`` to
``C:\Users\<USER>\anaconda3\DLLs`` or modify your PATH (`source <https://stackoverflow.com/a/55642416/13697228>`_).

Copy link
Member

Choose a reason for hiding this comment

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

I can't verify this due to lack of a developmental machine, is there anyone who can confirm this work?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I'm assuming anyone means core devs, but for reference, this was necessary for me to do on Windows to get pre-commit hooks working after following the contrib directions as closely as possible.

Copy link
Member

Choose a reason for hiding this comment

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

Well, yes, core devs (on a loose definition of the term), would be ideal. But I think we would also be satisfied with anyone other than the author confirming this. Thank you!

Copy link
Member

Choose a reason for hiding this comment

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

I can't replicate the issue on Windows - this seems like a little bit of an odd situation to have got into, and I'd suggest we shouldn't include the note on the basis that the linked source doesn't provide enough background about what's going on here for it to be clear that this is generally good advice.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Ok, maybe something weird on my end, then. Sounds good!

Copy link
Member

Choose a reason for hiding this comment

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

Are you planning to remove this note?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Sorry, yes, forgot about this one.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

pre-commit hooks in a conda environment on Windows have still been a huge pain. Unfortunately, my workaround has just been to uninstall the hooks in many cases.

Numba has started the process of using `type hints <https://www.python.org/dev/peps/pep-0484/>`_ in its code base. This
will be a gradual process of extending the number of files that use type hints, as well as going from voluntary to
mandatory type hints for new features. `Mypy <http://mypy-lang.org/>`_ is used for automated static checking.
Expand Down Expand Up @@ -415,12 +421,12 @@ It is built with `Sphinx <http://sphinx-doc.org/>`_ and
`numpydoc <https://numpydoc.readthedocs.io/>`_, which are available using
conda or pip; i.e. ``conda install sphinx numpydoc``.

To build the documentation, you need the bootstrap theme::
To build the documentation, you need the bootstrap and rtd themes::
Copy link
Member

Choose a reason for hiding this comment

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

Is this still accurate? RTD doesn't seem to install sphinx_bootstrap_theme: e.g. https://readthedocs.org/api/v2/build/15944491.txt

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I don't think it needs sphinx_bootstrap_theme.


$ pip install sphinx_bootstrap_theme
$ pip install sphinx_bootstrap_theme sphinx-rtd-theme
Copy link
Member

Choose a reason for hiding this comment

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

Two comments here. First, I thought this was mis-spelling, since my personal makefile contains sphinx_rtd_theme. But then I checked on anaconda.org and both sphinx_rtd_theme AND sphinx-rtd-theme exist.

Screen Shot 2021-09-06 at 13 13 07

Screen Shot 2021-09-06 at 13 12 43

Judging from downloads, I would tend to argue that sphinx_rtd_theme is probably what we want?

Also, I am not sure we actually need sphinx_bootstrap_theme. I do not have it in my environment:

Screen Shot 2021-09-06 at 13 19 34

And it builds fine. IIRC I think we switched from the bootstrap to the rtd theme some time ago but the docs were not updated.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Interestingly, when I read this, I even though it was a mispelling on my part, but when I went to https://github.com/readthedocs/sphinx_rtd_theme it turns out their instructions state pip install sphinx-rtd-theme. Probably fine to go with just sphinx_rtd_theme and leave out sphinx_bootstrap_theme since it doesn't seem to have been touched since 2019.

Copy link
Member

Choose a reason for hiding this comment

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

Ah, I though this was conda not pip. Are we asking people to pip install into a conda environment? Do we want to recommend conda instead, since the packages are available there?

Copy link
Member

Choose a reason for hiding this comment

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

Yeah, probably change this to conda install.


You can edit the source files under ``docs/source/``, after which you can
build and check the documentation::
build and check the documentation under ``docs/``::

$ make html
$ open _build/html/index.html
Expand Down