0.17.3: sphinx warnings `reference target not found`

[kloczek]

Fiirs of all currently it is not possible to use straight sphinx-build command to build documentation out of source tree

+ /usr/bin/sphinx-build -n -T -b man doc/source build/sphinx/man
Running Sphinx v4.5.0

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 332, in eval_config_file
    exec(code, namespace)
  File "/home/tkloczko/rpmbuild/BUILD/fasteners-0.17.3/doc/source/conf.py", line 19, in <module>
    from fasteners import version as fasteners_version
ModuleNotFoundError: No module named 'fasteners'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/cmd/build.py", line 272, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 202, in __init__
    self.config = Config.read(self.confdir, confoverrides or {}, self.tags)
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 165, in read
    namespace = eval_config_file(filename, tags)
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 345, in eval_config_file
    raise ConfigError(msg % traceback.format_exc()) from exc
sphinx.errors.ConfigError: There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 332, in eval_config_file
    exec(code, namespace)
  File "/home/tkloczko/rpmbuild/BUILD/fasteners-0.17.3/doc/source/conf.py", line 19, in <module>
    from fasteners import version as fasteners_version
ModuleNotFoundError: No module named 'fasteners'

Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 332, in eval_config_file
    exec(code, namespace)
  File "/home/tkloczko/rpmbuild/BUILD/fasteners-0.17.3/doc/source/conf.py", line 19, in <module>
    from fasteners import version as fasteners_version
ModuleNotFoundError: No module named 'fasteners'

This can be fixed by patch like below:

--- a/doc/source/conf.py~       2022-01-25 14:49:35.000000000 +0000
+++ b/doc/source/conf.py        2022-05-16 13:25:07.306879630 +0000
@@ -16,12 +16,12 @@
 import os
 import shlex

-from fasteners import version as fasteners_version
-
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('../..'))
+
+from fasteners import version as fasteners_version

 # -- General configuration ------------------------------------------------

This patch fixes what is in the comment and that cand of fix is suggested in sphinx example copy py https://www.sphinx-doc.org/en/master/usage/configuration.html#example-of-configuration-file

Than .. on building my packages I'm using sphinx-build command with -n switch which shows warmings about missing references. These are not critical issues. Here is the output with warnings:

+ /usr/bin/sphinx-build -n -T -b man doc/source build/sphinx/man
Running Sphinx v4.5.0
making output directory... done
WARNING: html_static_path entry '_static' does not exist
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 4 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-fasteners.3 { api/lock api/process_lock examples } <unknown>:1: WARNING: py:class reference target not found: fasteners.process_lock._FcntlLock
/home/tkloczko/rpmbuild/BUILD/fasteners-0.17.3/fasteners/process_lock.py:docstring of fasteners.process_lock._InterProcessLock.acquire:: WARNING: py:class reference target not found: int/float
/home/tkloczko/rpmbuild/BUILD/fasteners-0.17.3/fasteners/process_lock.py:docstring of fasteners.process_lock._InterProcessLock.acquire:: WARNING: py:class reference target not found: int/float
/home/tkloczko/rpmbuild/BUILD/fasteners-0.17.3/fasteners/process_lock.py:docstring of fasteners.process_lock._InterProcessLock.acquire:: WARNING: py:class reference target not found: int/float
<unknown>:1: WARNING: py:class reference target not found: fasteners.process_lock._FcntlInterProcessReaderWriterLock
/home/tkloczko/rpmbuild/BUILD/fasteners-0.17.3/fasteners/process_lock.py:docstring of fasteners.process_lock._InterProcessReaderWriterLock.acquire_read_lock:: WARNING: py:class reference target not found: int/float
/home/tkloczko/rpmbuild/BUILD/fasteners-0.17.3/fasteners/process_lock.py:docstring of fasteners.process_lock._InterProcessReaderWriterLock.acquire_read_lock:: WARNING: py:class reference target not found: int/float
/home/tkloczko/rpmbuild/BUILD/fasteners-0.17.3/fasteners/process_lock.py:docstring of fasteners.process_lock._InterProcessReaderWriterLock.acquire_read_lock:: WARNING: py:class reference target not found: int/float
/home/tkloczko/rpmbuild/BUILD/fasteners-0.17.3/fasteners/process_lock.py:docstring of fasteners.process_lock._InterProcessReaderWriterLock.acquire_write_lock:: WARNING: py:class reference target not found: int/float
/home/tkloczko/rpmbuild/BUILD/fasteners-0.17.3/fasteners/process_lock.py:docstring of fasteners.process_lock._InterProcessReaderWriterLock.acquire_write_lock:: WARNING: py:class reference target not found: int/float
/home/tkloczko/rpmbuild/BUILD/fasteners-0.17.3/fasteners/process_lock.py:docstring of fasteners.process_lock._InterProcessReaderWriterLock.acquire_write_lock:: WARNING: py:class reference target not found: int/float
done
build succeeded, 12 warnings.

You can peak on fixes that kind of issues in other projects https://github.com/latchset/jwcrypto/pull/289 https://github.com/click-contrib/sphinx-click/commit/abc31069

[psarka]

Thanks, but fasteners have migrated to mkdocs, so can't use your advice :(

I suppose you have some usecase where you want to build your own docs instead of using https://fasteners.readthedocs.io/en/latest/, could you try to build them from the current main and see if it works for you?

The current workflow (inside the source tree) is

python3.8 -m venv venv
source venv/bin/activate
pip install -r requirements-docs.txt
mkdocs build

(There are couple of warning for now)

[kloczek]

Thanks, but fasteners have migrated to mkdocs, so can't use your advice :(

That is really bad 😞 mkdosc does not support generating documentation as man pages 😢 Other thing is that sphinx can use .md files as input so it is possible to support mkdoc and sphinx.

mkdoc is used only in handfull modules. At rhe same time (looking on my already done spec fires used to build pytjon modules as rpm packages)

[tkloczko@devel-g2v SPECS]$ grep %sphinx_build_man python-* | wc -l; ls -1 python-*| wc -l
530
930

So statistically more than half (+5/9) modueles are using sphinx.

[psarka]

Do you need man pages because you are packaging fasteners as an rpm package? In that case I don't mind supporting something extra that would help generate those man pages (without switching to sphinx for online docs - those I want to keep mkdocs). Any advice? And maybe you have man pages for older versions of fasteners (or any other python lib) I'd like to see how they look like.

[kloczek]

Man page it is still most popular documentation format on all unix platforms and this is why I've choose that format as most usefull and handy for all rpm packges with sphinx based documentation. I've chose as well to put all modules documentation in python-<module_name>.3 files. By this access to all that documetation using bash/zsh/fish completions is incradibly easy. Example from my current devel system

[tkloczko@devel-g2v SPECS]$ man python-<tab><tab>
python-asttokens               python-fastjsonschema.         python-lxml                    python-prb                     python-sphinxcopybutton
python-attrs                   python-fonttools               python-markupsafe              python-prompt_toolkit          python-sphinx_rtd_theme
python-babel                   python-importlib-metadata      python-mock                    python-ptyprocess              python-sphinx-theme-alabaster
python-backcall                python-importlib_resources     python-mpi4py                  python-py                      python-testpath
python-beautifulsoup           python-ipython                 python-nbformat                python-pydata-sphinx-theme     python-testtools
python-build                   python-jedi                    python-numpydoc                python-pygments                python-tornado
python-charset-normalizer      python-Jinja                   python-olefile                 python-pyparsing               python-traitlets
python-cycler                  python-jmespath                python-parso                   python-pyrsistent              python-urllib3
python-cython                  python-jsonschema              python-pep517                  python-pytest                  python-wcwidth
python-decorator               python-jupyter_core            python-pillow                  python-requests                python-wheel
python-execnet                 python-kiwi                    python-pluggy                  python-setuptools              python-zipp

In that casse time-to-reach-documentation is way shorter tan accessing some web page which URL you must know. As well less provides way faster searching across such documentation than over web browser.

[kloczek]

IMO the best way would be leave current docs/ content as it is and add only docs/copy.py file to allow reuse all mkdoc files to be able generate out of those files documentation usig sphinx.

[psarka]

ok, I will take a look when I have a spare moment

[kloczek]

Gentle ping .. any update? 😋

[psarka]

No updates from my end, sorry about that, and thanks for the ping.

I had a quick google check now, and there are a couple of plugins that seem relevant. One of those is https://github.com/twardoch/mkdocs-combine, it should convert everything to pandoc and I assume that it is possible to convert that to man page. But it fails with error :(

Another is https://github.com/orzih/mkdocs-with-pdf. This one works, and converts everything to pdf. Maybe it is possible to hijack it's intermediate output and make a man page?

I still don't have time for this, if you would be willing to investigate these options, it would be great! :)

[psarka]

Ah, and this one, looks maintained, and converts to html: https://github.com/timvink/mkdocs-print-site-plugin

[kloczek]

Ah, and this one, looks maintained, and converts to html: https://github.com/timvink/mkdocs-print-site-plugin

This has nothing to do with man page (AKA roff output).

[psarka]

Sorry about that, I'm not familiar with the man page universe. I suppose this is not going to cut it? https://alldocs.app/convert-html-to-roff-man

[kloczek]

This is online service and I need something which can be executed on the system which is cut off from acces to the public networ 🤔 Sphinx provide rendering +15 output formats and mkdoc only one (html). Additionally it is used only in only handfull projects which in some cases have addiotionally possibility to generate documentation usinng sphinx.

[psarka]

I understand, but I'm not willing to migrate to sphinx only because of this use case. Note that the current docs were not migrated to mkdocs, but they were written from scratch in mkdocs. So I can't just undo something, I would need to find a sphinx theme that works for me, and migrate things there. This is too much work for too little benefit.

Anyway, could you give me hint on how do I view or compile and view this roff file? I would like to see how does the conversion result looks like.

[kloczek]

I'm not asking to migrate to sphinx. I'm asking to ADD/restore sphix support. Sphinx can use .md files as input resources (not only .rst).

Anyway, could you give me hint on how do I view or compile and view this roff file? I would like to see how does the conversion result looks like.

If we are talaking about sphinx I've already wrte that two times (look on forst line of that ticket)

+ /usr/bin/sphinx-build -n -T -b man doc/source build/sphinx/man

You can view resil using standard unix man command. Man page it is still most common documentation format used on all unix platforms (Linux is one of tha many unixes).

[psarka]

I think this does what you need, can you give it a try?

python -c "import yaml; f='mkdocs.yml'; d=yaml.safe_load(open(f)); d['plugins'].append('print-site'); yaml.safe_dump(d, open(f, 'w'))"
mkdocs build
pandoc -s ./site/print_page/index.html -t man -o fasteners.1

and then

man ./fasteners.1

You need the following dependencies for that:

pip install -r requirements-docs.txt 
pip install mkdocs-print-site-plugin
sudo apt install pandoc

[psarka]

Given the lack of feedback, I'll close this as complete.

[kloczek]

So you are not going to provide sphinx support? 🤔

[psarka]

To what end? I thought you needed a roff file, and that can be produced with three lines of code I wrote above.

[kloczek]

Look .. with sphinx is possible to render 16 output formats. With mkdos ONLY html.