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

sgbaird · 2021-09-04T02:45:43Z

Here's a summary:

There seems to be an issue in the docs related to the channel used for llvm
There seems to be a Windows-specific bug where conda can't find sqlite3.dll when trying to commit using the pre-commit hooks, so I added some instructions for overcoming that issue.
The docs can't build because it sphinx-rtd-theme isn't installed, so I added that to the pip install
I added instructions that make html is run under docs (should be obvious to anyone familiar with make, seeing as there is no MAKEFILE under docs/source, but saves someone the extra step)

Reference an existing issue

#7362 #7354

…lite3

… dev-docs

esc

Looking good so far, some open questions on the correct sphinx extensions to install. Thank you for working on this. 🙏

esc · 2021-09-06T11:09:30Z

docs/source/developer/contributing.rst

+   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>`_).
+


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

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.

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!

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.

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

Are you planning to remove this note?

Sorry, yes, forgot about this one.

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.

esc · 2021-09-06T11:21:33Z

docs/source/developer/contributing.rst


-   $ pip install sphinx_bootstrap_theme
+   $ pip install sphinx_bootstrap_theme sphinx-rtd-theme


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.

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:

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.

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.

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?

Yeah, probably change this to conda install.

esc

Update on installation procedure.

esc · 2021-09-06T15:38:11Z

docs/source/developer/contributing.rst


-   $ pip install sphinx_bootstrap_theme
+   $ pip install sphinx_bootstrap_theme sphinx-rtd-theme


Yeah, probably change this to conda install.

sgbaird · 2021-11-04T21:01:07Z

Changed it to conda install

esc · 2021-11-09T08:48:49Z

Changed it to conda install

Thank you! Once the reference to sqllite.dll has been removed I think this will be ready to merge!

@sgbaird thank you for your efforts on this front!

stuartarchibald · 2022-02-01T12:11:31Z

Just checking in on the state of this PR. @sgbaird was wondering if you have time to address the changes above, if not, it's no problem, one of the core developers can adopt the patch as needed. Many thanks.

gmarkall · 2022-02-01T14:25:56Z

docs/source/developer/contributing.rst

@@ -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::


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

I don't think it needs sphinx_bootstrap_theme.

gmarkall

Many thanks for the updates - this looks good to me now!

docs/source/developer/contributing.rst

gmarkall

Whoops, I need to walk back on my previous review - conda install sphinx-rtd-theme does not work, only pip provides a package with the dashes in the name as opposed to underscores.

Co-authored-by: Graham Markall <535640+gmarkall@users.noreply.github.com>

esc · 2023-01-27T14:32:28Z

@gmarkall I have resolved the conflicts on this one and submitted a fresh PR at: #8730 -- would you have some spare time to review it please? Thank you!

esc · 2023-05-04T12:33:52Z

#8730 has been marked as ready-to-merge -- closing this one now.

sgbaird added 3 commits September 3, 2021 20:19

add numba/label/ci_llvmlite_0.38 as channel and note about Windows sq…

c727f0c

…lite3

install rtd theme and note that build occurs under docs/ folder

ad41a7b

proper indentation

75da906

sgbaird requested review from esc, sklam and stuartarchibald as code owners September 4, 2021 02:45

sgbaird changed the title ~~Dev docs~~ developer contributing docs - llvm, sqlite3, sphinx-rtd-theme, and make html Sep 4, 2021

sgbaird and others added 3 commits September 3, 2021 21:04

change channel to numba/label/dev per esc comment

363d9e8

hyperlink had space

51dba44

Merge branch 'dev-docs' of https://github.com/sparks-baird/numba into…

6e979d2

… dev-docs

gmarkall added 3 - Ready for Review doc labels Sep 6, 2021

esc requested changes Sep 6, 2021

View reviewed changes

stuartarchibald added 4 - Waiting on author Waiting for author to respond to review Effort - medium Medium size effort needed and removed 3 - Ready for Review labels Sep 8, 2021

esc mentioned this pull request Oct 4, 2021

sphinx / numpydoc requires 0.37.0 of llvmlite but doc building requires 0.38.0 #7362

Closed

change pip to conda install

f4a67ef

gmarkall reviewed Feb 1, 2022

View reviewed changes

sgbaird added 2 commits February 1, 2022 20:16

remove reference about using pre-commit hooks on Windows

9431bf3

remove reference to bootstrap theme

3f408db

stuartarchibald added 4 - Waiting on reviewer Waiting for reviewer to respond to author and removed 4 - Waiting on author Waiting for author to respond to review labels Feb 2, 2022

gmarkall approved these changes Mar 9, 2022

View reviewed changes

gmarkall reviewed Mar 9, 2022

View reviewed changes

docs/source/developer/contributing.rst Outdated Show resolved Hide resolved

gmarkall requested changes Mar 9, 2022

View reviewed changes

Update docs/source/developer/contributing.rst

59e6da1

Co-authored-by: Graham Markall <535640+gmarkall@users.noreply.github.com>

esc mentioned this pull request Jan 27, 2023

Update dev-docs #8730

Merged

esc closed this May 4, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

sgbaird commented Sep 4, 2021

esc left a comment

esc Sep 6, 2021

sgbaird Sep 6, 2021

esc Sep 6, 2021

gmarkall Sep 6, 2021

sgbaird Sep 6, 2021

gmarkall Nov 8, 2021

sgbaird Nov 8, 2021

sgbaird Feb 2, 2022

esc Sep 6, 2021

sgbaird Sep 6, 2021

esc Sep 6, 2021

esc Sep 6, 2021

esc left a comment

esc Sep 6, 2021

sgbaird commented Nov 4, 2021

esc commented Nov 9, 2021

stuartarchibald commented Feb 1, 2022

gmarkall Feb 1, 2022

sgbaird Feb 2, 2022

gmarkall left a comment

gmarkall left a comment

esc commented Jan 27, 2023

esc commented May 4, 2023


		$ pip install sphinx_bootstrap_theme
		$ pip install sphinx_bootstrap_theme sphinx-rtd-theme

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

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

Conversation

sgbaird commented Sep 4, 2021

Reference an existing issue

esc left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

esc left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sgbaird commented Nov 4, 2021

esc commented Nov 9, 2021

stuartarchibald commented Feb 1, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gmarkall left a comment

Choose a reason for hiding this comment

gmarkall left a comment

Choose a reason for hiding this comment

esc commented Jan 27, 2023

esc commented May 4, 2023