Pyzmq: Generation of html help files from source - the methods of sphinx don't work

[AnthonyTheKoala]

I would like an offline version of the help files.

Been to the site pyzmnq at https://github.com/zeromq/pyzmq
Downloaded the zip file at https://github.com/zeromq/pyzmq/archive/master.zip
Unzipped the zip file, went to 'docs' folder

Unfortunately, when double-clicking on the index.html I don't get the lovely presentation as the online version at https://pyzmq.readthedocs.io/en/latest/.

Looking at the build folder of the supposed sphinx generated html files, NOT ALL files were generated.

Need guidance how to build the pyzmq's *.rst files can be completely compiled to *.html as the online guidance did not make me wiser.

Thank you,
Anthony of Sydney

[AnthonyTheKoala]

Apologies, this is about generating the *.html files from the *.rst files for the pyzmq.

Apologies - when using the sphinx to convert the *.rst to *.html (i) the appearance of the offline version did not look like the online presentation and (ii) it appears that the not all *.html files were generated and (iii) I did not have the ability to control the location of the build folder for the pyzmq's documentation.

Thank you,
Anthony of Sydney

[kinow]

Hi @AnthonyTheKoala

I think I generated the docs for pyzmq a few times. From what I recall, you should be able to try the following:

$ python -m venv venv
$ source ./venv/bin/activate
(venv) $ pip install -e .
(venv) $ cd docs
(venv) $ pip install -r requirements.txt
(venv) $ make html

If no errors raised for these commands, the docs should be available locally at build/html/index.html. You can either open index.html in your browser (maybe even drag & drop if you'd like), or

(venv) $ cd html/build/
(venv) $ python -m http.server 9090

The last command starts an HTTP server with Python listening to whatever port you provided, so http://localhost:9090/ in this case would have the pyzmq docs.

Bruno
(from across the ditch :wave: )

[AnthonyTheKoala]

Prezado Senhor Bruno,
Obrigado por sua resposta. (used google translate from English -> Portuguese).

I tried and got the same result as my previous attempts to build the docs

In addition there were no subheadings as what it is on the online version:

Remark: There appears to be a difference between downloading the zip file and gitting it.
To illustrate:
I go to https://github.com/zeromq/pyzmq and go to the "code" dropdown list.

If I download the file, https://github.com/zeromq/pyzmq/archive/master.zip it's less than < 1MB. There is a subfolder docs. That was the source docs file.

However from previous experience of gitting source files, the resulting download is far greater than 1MB.

It seems that by gitting the repository there are more files. Because from previous experience of gitting, the repository is much larger than the *.zip file. Would it be that I should git the file like this:

git --recursive https://github.com/zeromq/pyzmq.git

Thank you,
By the way when are you going to write "PyZMQ Basics Part 2", I saved part 1 as a pdf file. I came across the pyzmq package and found that it was easier to set up client/server than normal sockets.

Obrigado,através do Mar da Tasmânia com água cobrindo a vala. (using google translate and re-translating to ensure translation consistency)
Anthony de Sydney,

[AnthonyTheKoala]

Dear Bruno,
Don't know why the jpg file of the code download methods from github didn't show, here it is

Thank you, obrigado, gracias, ありがとうございました
Anthony from Sydney

[kinow]

Hi @AnthonyTheKoala !

I'm impressed by how correct Google Translate is (and polite :smile: )!

I tried and got the same result as my previous attempts to build the docs

The contents should be the same on the live documentation, and on your local version. But in readthedocs they use a theme when deploying it.

If you want that exact look and feel, try the following:

(venv) $ pip install sphinx-rtd-theme

Then change in docs/src/conf.py to load the extension and use the theme provided by the extension.

diff --git a/docs/source/conf.py b/docs/source/conf.py
index cd6ee5a..cf1cc77 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -36,6 +36,7 @@ extensions = [
               'sphinx.ext.autodoc',
               'sphinx.ext.intersphinx',
               'sphinx.ext.napoleon',
+              'sphinx_rtd_theme',
               ]

 # Add any paths that contain templates here, relative to this directory.
@@ -116,7 +117,7 @@ suppress_warnings = ['epub.unknown_project_files']

 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-# html_theme = 'default'
+html_theme = 'sphinx_rtd_theme'

 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

That should give you a version similar to what is live in ReadTheDocs.

Is that what you were looking for?

Remark: There appears to be a difference between downloading the zip file and gitting it.

It could be correct. The files in the GitHub release are uploaded there either from a tag, or after it was built. So the contents could differ I think?

By the way when are you going to write "PyZMQ Basics Part 2", I saved part 1 as a pdf file. I came across the pyzmq package and found that it was easier to set up client/server than normal sockets.

Ha! You found that blog post. We are still using REQ/REP, but will move to PUB/SUB or another pattern soon. I am planning to write part 2 when that happens :-)

Cheers
Bruno

[AnthonyTheKoala]

Dear Bruno,
Thank you for your time.
This is about the conf.py file. I found it. The conf.py file is generated by sphinx.
Having a look at the structure of the file, there is a section for different file formats, and html is one of them.
Lots of comments in the html section.
Should I replace the text for the html section with this:

diff --git a/docs/source/conf.py b/docs/source/conf.py
index cd6ee5a..cf1cc77 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -36,6 +36,7 @@ extensions = [
               'sphinx.ext.autodoc',
               'sphinx.ext.intersphinx',
               'sphinx.ext.napoleon',
+              'sphinx_rtd_theme',
               ]

 # Add any paths that contain templates here, relative to this directory.
@@ -116,7 +117,7 @@ suppress_warnings = ['epub.unknown_project_files']

 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-# html_theme = 'default'
+html_theme = 'sphinx_rtd_theme'

Then run

python conf.py

Thank you again,
Anthony from Sydney

[kinow]

Dear Bruno,
Thank you for your time.

Don't mention it :-) I think you are very close to generating the documentation as you expected/needed.

The conf.py file is generated by sphinx.

The conf.py is the configuration file used by Sphinx.

Having a look at the structure of the file, there is a section for different file formats, and html is one of them.
Lots of comments in the html section.

Correct! :+1:

Should I replace the text for the html section with this:

Yes, but remember you also have to install the extension with pip as in the comment above. Sphinx is a Python module, that loads other modules as extensions. What you are doing here is telling Sphinx that you have installed a module/extension, you want it to load the extension, and also to use that as theme (there are other types of extensions).

Then run

python conf.py

You don't need to run conf.py. Just edit it. Then go back to the docs folder, where you have the Makefile file. Look at the instructions I posted above :point_up: and run make html.

This time, instead of using the default theme, it will use the ReadTheDocs theme, and the final local documentation should look like the website docs. (:crossed_fingers: !)

[AnthonyTheKoala]

Dear Bruno,
Unfortunately it did not work.
(1) Installed the 'read the docs' template

$ pip install sphinx-rtd-theme

(2) Replaced all the code & comments in the conf.py file

diff --git a/docs/source/conf.py b/docs/source/conf.py
index cd6ee5a..cf1cc77 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -36,6 +36,7 @@ extensions = [
               'sphinx.ext.autodoc',
               'sphinx.ext.intersphinx',
               'sphinx.ext.napoleon',
+              'sphinx_rtd_theme',
               ]

 # Add any paths that contain templates here, relative to this directory.
@@ -116,7 +117,7 @@ suppress_warnings = ['epub.unknown_project_files']

(4) In the 'docs/src' subdirectory

make html

(5) Invoking the server at c:/python38/build/html

python -m http.server 9090

(6) :( got this again

Is there something that is a missing step?

Thank you,
Anthony of Sydney

[kinow]

Strange. Could you try make clean html?

[AnthonyTheKoala]

Dear Bruno,
Despite your browser showing the "read the docs" version" the following did not provide the desired result.

rem in the docs subfolder, make clean html should be:
make html clean
rem so far so good
cd c:/python38/build html
python -m http.server 9090

Goto my browser and put this in:

localhost:9090/index.html

Unfortunately did not work.
There must be something missing that I must do.
Thank you,
Anthony of Sydney

[kinow]

Hmm, I'm out of ideas @AnthonyTheKoala :worried: maybe try starting from scratch in a blank environment, or see if it works on another PC, or maybe in a Linux VM/container? (I think you are using Windows?)

[AnthonyTheKoala]

Dear Bruno,
Thank you for your patience.
I do have a Win 7 environment and a Python 3.8.6 environment. This is in addition a c:/msys64/mingw32 bash window, c:/msys64/mingw64 bash window and a git bash window.
I'll be having a go at downloading the repository by gitting it. Based on experience, downloading a repository by gitting it takes a long time.
Thank you,
Anthony of Sydney

[kinow]

No worries, hopefully it will work. I have a Windows 10 pro box, but it's at the office and I work-from-home for the next couple days. In case you are still having problems by Thu/Fri, I should be able to try on that box. I use Anaconda 3 prompt on Windows (even though I use Anaconda, I still create a virtual environment with pip)

[AnthonyTheKoala]

Dear Bruno,
I'm avoiding an anconda/miniconda environment. 99% of my successful installations were without anaconda/miniconda. In regards the venv, I still get the same results whether venv or no venv.
Thank you,
Anthony of Sydney

[AnthonyTheKoala]

Dear Bruno,
Estou animado para dizer que encontrei uma solução para o meu problema. Não requer o uso do servidor Python. (using google translate)
When you told me about the RTD style of html documentation from this:

pip install sphinx-rtd-theme

I did further research into Sphynx's RTD theme and found that there is a simpler answer. In addition, as I said at the top of this reply, I don't even need to run the Python server!
Even the conf.py needs to be very simple.

Here are the steps of installing the html files from the rst files.

(1)
I placed pyzmq's docs folder in c:\python38\thing
in the docs folder.
run in a dos window

sphinx-quickstart
> Please enter a new root path  []: c:\python38\thing
> Separate source and build directories (y/n) [n]: y
> Project name: pyzmq
> Author names(x): various
> Project release []: 19.0.2
> Project language [en]:English

(2)
goto the c:\python38\thing folder
edit the make.bat
modify the following lines

set SOURCEDIR= whatever
set BUILDDIR = whatever

to

set SOURCEDIR=C:\python38\thing\docs
set BUILDDIR=c:\python38\thing

(3)
in C:\python38\thingdocs\source
edit conf.py
replace all the code with this

import sphinx_rtd_theme
extensions = ['sphinx_rtd_theme']
html_theme = "sphinx_rtd_theme"

(4)
in the location of the make.bat file,

make html

Remark, during the building process, there were 91 warnings, typically of the type

.. autofunction:: zmq.utils.z85.encode
c:\python38\thing\docs\source\index.rst:41: WARNING: Undefined substitution referenced: "target_libzmq".

But generally there was a successful compile

looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] unicode
generating indices...  genindexdone
writing additional pages...  searchdone
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 91 warnings.

So I have a successful running of the html file like the screenshot

The only inconvenience is that when you want to go to the top entry search line in the left-side menu, you may have to reduce the size of the screen.

Anyway it works.
Thank you, merci, gracias, gracie, obgrigado, ありがとう
Anthony from Sydney across the ditch covered in water.

[kinow]

Glad it worked @AnthonyTheKoala ! I think the issue can be closed then :+1:

[AnthonyTheKoala]

Dear Bruno,
Thank you for assistance.
Bye!
Anthony of Sydney