dataflake
commented
2 months ago The Sphinx configuration has changed dramatically and this is no longer applicable.
Closed kloczek closed 2 months ago
dataflake
commented
2 months ago The Sphinx configuration has changed dramatically and this is no longer applicable.
kloczek
commented
2 months ago Just checked master and still that patch is not added and still I see he same warnings
All because none changes abut typing has been added.
kloczek
commented
2 months ago On top of that looks like with what is on master pytest is failing
dataflake
commented
2 months ago The supported way to build the docs is using tox, the tox docs configuration sets up everything and the documentation builds without errors.
We do not use pytest and do not guarantee compatibility with it.
kloczek
commented
2 months ago Those warnings have nothing to do with tox. It is pure result of use -i option.
kloczek
commented
1 month ago Gentle ping .. did you try to add to tox.ini -i option like blow?
--- a/tox.ini
+++ b/tox.ini
@@ -80,5 +80,5 @@
skip_install = false
commands_pre =
commands =
- sphinx-build -b html -d docs/_build/doctrees docs docs/_build/html
- sphinx-build -b doctest -d docs/_build/doctrees docs docs/_build/doctest
+ sphinx-build -b html -i -d docs/_build/doctrees docs docs/_build/html
+ sphinx-build -b doctest -i -d docs/_build/doctrees docs docs/_build/doctest
Additionally warnings
WARNING: autodoc: failed to import class 'mapping.PersistentMapping' from module 'persistent'; the following exception was raised:
No module named 'persistent' [autodoc.import_object]
WARNING: autodoc: failed to import class 'list.PersistentList' from module 'persistent'; the following exception was raised:
No module named 'persistent' [autodoc.import_object]
WARNING: autodoc: failed to import module 'interfaces' from module 'persistent'; the following exception was raised:
No module named 'persistent' [autodoc.import_object]
WARNING: autodoc: failed to import class 'Persistent' from module 'persistent'; the following exception was raised:
No module named 'persistent' [autodoc.import_object]Seems related to issues reported by pytest https://github.com/zopefoundation/persistent/issues/172
dataflake
commented
1 month ago The tox run works and shows no warnings:
$ bin/tox -edocs
docs: install_deps> python -I -m pip install 'setuptools<74'
.pkg: install_requires> python -I -m pip install 'setuptools<74'
.pkg: _optional_hooks> python /Users/jens/src/zope/persistent/lib/python3.11/site-packages/pyproject_api/_backend.py True setuptools.build_meta
.pkg: get_requires_for_build_sdist> python /Users/jens/src/zope/persistent/lib/python3.11/site-packages/pyproject_api/_backend.py True setuptools.build_meta
.pkg: install_requires_for_build_sdist> python -I -m pip install 'cffi; platform_python_implementation == "CPython"' 'cffi>=1.17.0rc1; platform_python_implementation == "CPython" and python_version >= "3.13a0"'
.pkg: get_requires_for_build_wheel> python /Users/jens/src/zope/persistent/lib/python3.11/site-packages/pyproject_api/_backend.py True setuptools.build_meta
.pkg: install_requires_for_build_wheel> python -I -m pip install 'cffi; platform_python_implementation == "CPython"' 'cffi>=1.17.0rc1; platform_python_implementation == "CPython" and python_version >= "3.13a0"'
.pkg: prepare_metadata_for_build_wheel> python /Users/jens/src/zope/persistent/lib/python3.11/site-packages/pyproject_api/_backend.py True setuptools.build_meta
.pkg: build_sdist> python /Users/jens/src/zope/persistent/lib/python3.11/site-packages/pyproject_api/_backend.py True setuptools.build_meta
docs: install_package_deps> python -I -m pip install Sphinx 'cffi; platform_python_implementation == "CPython"' 'cffi>=1.17.0rc1; platform_python_implementation == "CPython" and python_version >= "3.13a0"' manuel repoze.sphinx.autointerface sphinx-rtd-theme zope.deferredimport zope.interface zope.testrunner
docs: install_package> python -I -m pip install --force-reinstall --no-deps /Users/jens/src/zope/persistent/.tox/.tmp/package/1/persistent-6.2.dev0.tar.gz
docs: commands[0]> sphinx-build -b html -d docs/_build/doctrees docs docs/_build/html
Running Sphinx v7.4.7
loading translations [en]... done
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 10 source files that are out of date
updating environment: 0 added, 3 changed, 0 removed
reading sources... [100%] changes
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets...
copying static files... done
copying extra files... done
copying assets: done
writing output... [100%] using
generating indices... genindex py-modindex done
writing additional pages... search done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.
The HTML pages are in docs/_build/html.
docs: commands[1]> sphinx-build -b doctest -d docs/_build/doctrees docs docs/_build/doctest
Running Sphinx v7.4.7
loading translations [en]... done
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
writing output...
building [doctest]: targets for 10 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
reading sources...
looking for now-outdated files... none found
running tests...
Document: api/attributes
------------------------
1 items passed all tests:
80 tests in default
80 tests in 1 items.
80 passed and 0 failed.
Test passed.
Document: using
---------------
1 items passed all tests:
97 tests in default
97 tests in 1 items.
97 passed and 0 failed.
Test passed.
Document: api/pickling
----------------------
1 items passed all tests:
68 tests in default
68 tests in 1 items.
68 passed and 0 failed.
Test passed.
Document: api/cache
-------------------
1 items passed all tests:
11 tests in default
11 tests in 1 items.
11 passed and 0 failed.
Test passed.
Doctest summary
===============
256 tests
0 failures in tests
0 failures in setup code
0 failures in cleanup code
build succeeded.
Testing of doctests in the sources finished, look at the results in docs/_build/doctest/output.txt.
docs: OK (10.76=setup[8.77]+cmd[1.78,0.20] seconds)
congratulations :) (10.79 seconds)The tox run works and shows no warnings:
Please add in tox configuration to run sphinx-build with additional option -i and you will be able to see all those warnings.
dataflake
commented
1 month ago Building the docs with tox -edocs is the supported way of building the docs for this package and it works without error or warning. There is no point in exploring an unsupported way of building the docs.
kloczek
commented
1 month ago Again .. tox docs target is not using -i param in sphinh-build command.
PLEASE try to use below patch ad rerun tox
--- a/tox.ini
+++ b/tox.ini
@@ -80,5 +80,5 @@
skip_install = false
commands_pre =
commands =
- sphinx-build -b html -d docs/_build/doctrees docs docs/_build/html
- sphinx-build -b doctest -d docs/_build/doctrees docs docs/_build/doctest
+ sphinx-build -b -i html -d docs/_build/doctrees docs docs/_build/html
+ sphinx-build -b -i doctest -d docs/_build/doctrees docs docs/_build/doctest
``There is no point breaking the working tox invocation by adding flags. Please stop posting about it.
kloczek
commented
1 month ago This is not about breaking anything. Those warnings shows in which one places in for example htlm, pdq, qch and probably fe other places there is only highlighted keyword without link. Really PLEAE check html output using web browser. I'm generating roff output (man page) so I'm not affected by those warnings however any other output with hyperlinks is affected by those warnings.
dataflake
commented
1 month ago OK, I applied your changes as you proposed them.
First try:
...
docs: commands[0]> sphinx-build -b -i html -d docs/_build/doctrees docs docs/_build/html
usage: sphinx-build [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]
sphinx-build: error: argument --builder/-b: expected one argument
docs: exit 2 (0.17 seconds) /Users/jens/src/zope/persistent> sphinx-build -b -i html -d docs/_build/doctrees docs docs/_build/html pid=92853
docs: FAIL code 2 (4.41=setup[4.24]+cmd[0.17] seconds)
evaluation failed :( (4.47 seconds)So obviously the -i cannot be right after -b. Second try:
...
docs: commands[0]> sphinx-build -i -b html -d docs/_build/doctrees docs docs/_build/html
usage: sphinx-build [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]
sphinx-build: error: unrecognized arguments: -i
docs: exit 2 (0.09 seconds) /Users/jens/src/zope/persistent> sphinx-build -i -b html -d docs/_build/doctrees docs docs/_build/html pid=93067
docs: FAIL code 2 (3.75=setup[3.65]+cmd[0.09] seconds)
evaluation failed :( (3.77 seconds)Also, running .tox/docs/bin/sphinx-build -h does not even show an option -i. The version of Sphinx is 7.4.7 because the chosen Sphinx theme, sphinx-rtd-theme, requires Sphinx<8.
dataflake
commented
1 month ago P.S.: sphinx-build from Sphinx 8.0.2 does not seem to know the -i flag, either, so I have no idea what you're doing.
kloczek
commented
1 month ago Correction: please use -n option.
[tkloczko@pers-jacek SPECS]$ sphinx-build --help | grep nit
--nitpicky, -n nitpicky mode: warn about all missing referencesOK, now I see warnings. There are no import warnings during the tox run because the module can be imported. The rest, like you said yourself, are not critical. Feel free to propose a PR.
kloczek
commented
1 month ago Than .. on building my packages I'm using
sphinx-buildcommand with-nswitch which shows warmings about missing references. These are not critical issues.
Good that you just wrote whit I've mentioned on opening ticket ("These are not critical issues"). I have no time to fix that and those warnings are not affecting my build procedure). I'm only messenger.
Just please keep this ticket opened .. maybe someone else will fix that.
First of all currently it is not possible to use straight
sphinx-buildcommand to build documentation out of source treeFirst part of warnings can be fixed by patch like below:
This patch fixes what is in the comment and that can 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-buildcommand with-nswitch which shows warmings about missing references. These are not critical issues.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 https://github.com/latchset/jwcrypto/pull/289 https://github.com/RDFLib/rdflib-sqlalchemy/issues/95 https://github.com/sissaschool/elementpath/commit/bf869d9e https://github.com/jaraco/cssutils/issues/21