search

sphinx-contrib / sphinxcontrib-towncrier

An RST directive for injecting a Towncrier-generated changelog draft containing fragments for the unreleased (next) project version. Demo: https://ansible-pylibssh.rtfd.io/changelog. Docs: https://sphinxcontrib-towncrier.rtfd.io
https://pypi.org/p/sphinxcontrib-towncrier
BSD 3-Clause "New" or "Revised" License
18 stars 18 forks source link

0.2.0a0 + master: build_sphings warnings and some other issues with building socumentation #52

Closed kloczek closed 3 years ago

kloczek commented 3 years ago

First just "setup.py build" Than :

+ PYTHONPATH=$PWD/build/lib SETUPTOOLS_SCM_PRETEND_VERSION=0.2.0a0 /usr/bin/python3 setup.py build_sphinx -b man --build-dir build/sphinx
running build_sphinx
Running Sphinx v4.0.2
loading translations [en]... done

Extension error:
Could not import extension sphinxcontrib.towncrier (exception: No module named 'sphinxcontrib.towncrier')

I've checked that with strace and:

openat(AT_FDCWD, "/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/build/lib", O_RDONLY|O_NONBLOCK|O_CLOEXEC|O_DIRECTORY) = 3
newfstatat(AT_FDCWD, "/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/build/lib", {st_mode=S_IFDIR|0755, st_size=26, ...}, 0) = 0
newfstatat(AT_FDCWD, "/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/build/lib", {st_mode=S_IFDIR|0755, st_size=26, ...}, 0) = 0
newfstatat(AT_FDCWD, "/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/build/lib", {st_mode=S_IFDIR|0755, st_size=26, ...}, 0) = 0
newfstatat(AT_FDCWD, "/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/build/lib/sphinxcontrib/__init__.cpython-38-x86_64-linux-gnu.so", 0x7ffd845bbfd0, 0) = -1 ENOENT (No such file or directory)
newfstatat(AT_FDCWD, "/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/build/lib/sphinxcontrib/__init__.abi3.so", 0x7ffd845bbfd0, 0) = -1 ENOENT (No such file or directory)
newfstatat(AT_FDCWD, "/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/build/lib/sphinxcontrib/__init__.so", 0x7ffd845bbfd0, 0) = -1 ENOENT (No such file or directory)
newfstatat(AT_FDCWD, "/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/build/lib/sphinxcontrib/__init__.py", 0x7ffd845bbfd0, 0) = -1 ENOENT (No such file or directory)
newfstatat(AT_FDCWD, "/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/build/lib/sphinxcontrib/__init__.pyc", 0x7ffd845bbfd0, 0) = -1 ENOENT (No such file or directory)
newfstatat(AT_FDCWD, "/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/build/lib/sphinxcontrib", {st_mode=S_IFDIR|0755, st_size=18, ...}, 0) = 0

So I've added > build/lib/sphinxcontrib/__init__.py to create empty file for which is loooking sphinx and documentation builds but with some warnings:

+ /usr/bin/python3 setup.py build_sphinx -b man --build-dir build/sphinx
running build_sphinx
Running Sphinx v4.0.2
loading translations [en]... done
making output directory... done
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://docs.rtfd.io/en/stable/objects.inv...
loading intersphinx inventory from https://setuptools.rtfd.io/en/latest/objects.inv...
loading intersphinx inventory from https://www.sphinx-doc.org/en/master/objects.inv...
intersphinx inventory has moved: https://docs.rtfd.io/en/stable/objects.inv -> https://docs.readthedocs.io/en/stable/objects.inv
intersphinx inventory has moved: https://setuptools.rtfd.io/en/latest/objects.inv -> https://setuptools.readthedocs.io/en/latest/objects.inv
myst v0.15.1: MdParserConfig(renderer='sphinx', commonmark_only=False, enable_extensions=['dollarmath'], dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', disable_syntax=[], url_schemes=['http', 'https', 'mailto', 'ftp'], heading_anchors=None, heading_slug_func=None, html_meta=[], footnote_transition=True, substitutions=[], sub_delimiters=['{', '}'], words_per_minute=200)
Creating file /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/docs/pkg/sphinxcontrib.rst.
Creating file /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/docs/pkg/sphinxcontrib.towncrier.rst.
Creating file /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/docs/pkg/sphinxcontrib.towncrier._scm_version.rst.
Creating file /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/docs/pkg/sphinxcontrib.towncrier._towncrier.rst.
Creating file /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/docs/pkg/sphinxcontrib.towncrier._version.rst.
Creating file /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/docs/pkg/modules.rst.
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 9 added, 0 changed, 0 removed
reading sources... [100%] pkg/sphinxcontrib.towncrier._version
WARNING: Missing key 'towncrier' in file /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/pyproject.toml
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... sphinxcontrib-towncrier.1 { change-notes-layout contributing pkg/modules pkg/sphinxcontrib pkg/sphinxcontrib.towncrier pkg/sphinxcontrib.towncrier._scm_version pkg/sphinxcontrib.towncrier._towncrier pkg/sphinxcontrib.towncrier._version } done
build succeeded, 1 warning.
webknjaz commented 3 years ago

First just "setup.py build"

Don't do this. This is an incorrect way of doing whatever you wanted to do with this command. It is NOT supported.

+ PYTHONPATH=$PWD/build/lib

I don't know what's in this dir but sounds like you've produced something in a wrong way and now Python's import machinery can't find it.

SETUPTOOLS_SCM_PRETEND_VERSION=0.2.0a0 /usr/bin/python3 setup.py build_sphinx -b man --build-dir build/sphinx

We don't have manpages. What did you expect here?

Extension error: Could not import extension sphinxcontrib.towncrier (exception: No module named 'sphinxcontrib.towncrier')

Python's import machinery didn't find it.

So I've added > build/lib/sphinxcontrib/__init__.py to create empty file for which is loooking sphinx

No, it's Python's import machinery that scans the file system, not Sphinx itself. Also, wrong hack: init is unnecessary because this project uses an implicit namespace that is natively supported by Python 3. Only Python 2 projects need it. By injecting such files, you'll create conflicts with other packages in the sphinxcontrib namespace.

+ /usr/bin/python3 setup.py build_sphinx -b man --build-dir build/sphinx

Abusing setuptools as a runner for arbitrary commands like sphinx is not supported. I think even setuptools is deprecating this misuse. Also, as per above: we don't build man pages.

WARNING: Missing key 'towncrier' in file /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/pyproject.toml

This doesn't seem to be happening on master as executed with the supported methods.

kloczek commented 3 years ago

First just "setup.py build"

Don't do this. This is an incorrect way of doing whatever you wanted to do with this command. It is NOT supported.

Please clarify why ..

+ PYTHONPATH=$PWD/build/lib

I don't know what's in this dir but sounds like you've produced something in a wrong way and now Python's import machinery can't find it.

This directory contains products of the setuptools build command (setup.py builds) Thi smethod works across almost all python modules ans tthers in no reasons why it should not work in case of your module.

SETUPTOOLS_SCM_PRETEND_VERSION=0.2.0a0 /usr/bin/python3 setup.py build_sphinx -b man --build-dir build/sphinx

We don't have manpages. What did you expect here?

You dont need to have it. Sphinx supprts many otput formats and you don;t need to supporrt those formats. From sphinx-build(1):

OPTIONS
       -b buildername
              The most important option: it selects a builder.  The most common builders are:

              html   Build HTML pages.  This is the default builder.

              dirhtml
                     Build HTML pages, but with a single directory per document.  Makes for prettier URLs (no .html) if served from a webserver.

              singlehtml
                     Build a single HTML with the whole content.

              htmlhelp, qthelp, devhelp, epub
                     Build HTML files with additional information for building a documentation collection in one of these formats.

              applehelp
                     Build an Apple Help Book.  Requires hiutil and codesign, which are not Open Source and presently only available on Mac OS X 10.6 and higher.

              latex  Build LaTeX sources that can be compiled to a PDF document using pdflatex.

              man    Build manual pages in groff format for UNIX systems.

              texinfo
                     Build Texinfo files that can be processed into Info files using makeinfo.

              text   Build plain text files.

              gettext
                     Build gettext-style message catalogs (.pot files).

              doctest
                     Run all doctests in the documentation, if the doctest extension is enabled.

              linkcheck
                     Check the integrity of all external links.

              xml    Build Docutils-native XML files.

              pseudoxml
                     Build compact pretty-printed "pseudo-XML" files displaying the internal structure of the intermediate document trees.

              See /usage/builders/index for a list of all builders shipped with Sphinx.  Extensions can add their own builders.

Extension error: Could not import extension sphinxcontrib.towncrier (exception: No module named 'sphinxcontrib.towncrier')

Python's import machinery didn't find it.

So I've added > build/lib/sphinxcontrib/__init__.py to create empty file for which is loooking sphinx

No, it's Python's import machinery that scans the file system, not Sphinx itself. Also, wrong hack: init is unnecessary because this project uses an implicit namespace that is natively supported by Python 3. Only Python 2 projects need it. By injecting such files, you'll create conflicts with other packages in the sphinxcontrib namespace.

So what is tej proper hack?

+ /usr/bin/python3 setup.py build_sphinx -b man --build-dir build/sphinx

Abusing setuptools as a runner for arbitrary commands like sphinx is not supported. I think even setuptools is deprecating this misuse. Also, as per above: we don't build man pages.

It is supported everywhere. I have at the moment +500 pythom modules packaged in rpm packages. Result:

[tkloczko@barrel SPECS]$ man python-
Display all 209 possibilities? (y or n)
python-amqp                           python-GitPython.tex                  python-path                           python-sphinxcontrib-programoutput
python-anytree                        python-greenlet                       python-pillow                         python-sphinxcopybutton
python-argcomplete                    python-h2                             python-pluggy                         python-sphinxext-opengraph
python-arrow                          python-hacking                        python-polib                          python-sphinx-hoverxref
python-"asgi                          python-httplib2                       python-prb                            python-sphinx-inline-tabs
python-aspectlib                      python-hyperframe                     python-priority                       python-sphinx-removed-in
python-astor                          python-hyperlink                      python-productmd-compose              python-sphinx_rtd_theme
python-astroid                        python-hypothesis                     python-productmd-composeinfo          python-sphinx-tabs
python-async_generator                python-ifaddr                         python-productmd-discinfo             python-sphinx-typlog-theme
python-atomicwrites                   python-importlib-metadata             python-productmd-images               python-sphobjinv
python-attrs                          python-inflect                        python-productmd-rpms                 python-sqlparse
python-augeas                         python-ipykernel                      python-productmd-terminology          python-stdlib-list
python-autodocsumm                    python-itsdangerous                   python-productmd-treeinfo             python-stem
python-babel                          python-jaraco-classes                 python-prompt_toolkit                 python-sure
python-backcall                       python-jaraco-envs                    python-ptyprocess                     python-sybil
python-benchmark                      python-jaraco-functools               python-purl                           python-systemd
python-betamax                        python-jaraco.itertools               python-py                             python-terminado
python-billiard                       python-jaraco-packaging               python-pyasn1                         python-testpath
python-bleach                         python-jaraco-text                    python-pycodestyle                    python-testrepository
python-blinker                        python-jedi                           python-pyfakefs                       python-testtools
python-boto3                          python-Jinja                          python-pygal                          python-tidy
python-botocore                       python-jmespath                       python-pygments                       python-tinycss2
python-bottle                         python-jupyter_client                 python-pyhamcrest                     python-tornado
python-breathe                        python-jupyter_core                   python-pylama                         python-traitlets
python-build                          python-kiwi                           python-pylint                         python-trio
python-cachetools                     python-kombu                          python-pymeeus                        python-trustme
python-case                           python-lark                           python-pynacl                         python-twisted
python-cffi                           python-lazy-object-proxy              python-pyopenssl                      python-uritemplate
python-characteristic                 python-libevdev                       python-pyrad                          python-urllib3
python-chardet                        python-linkify-it-py                  python-pyrsistent                     python-validators
python-click                          python-lockfile                       python-pyscss                         python-vine
python-click-log                      python-lxml                           python-pytest                         python-waitress
python-contextlib2                    python-mako                           python-pytest-checkdocs               python-wcwidth
python-convertdate                    python-markupsafe                     python-pytest-cov                     python-webcolors
python-coveragepy                     python-mdit-py-plugins                python-pytest-regressions             python-webencodings
python-cppy                           python-mistune                        python-pytest-runner                  python-webob
python-cssselect2                     python-more-itertools                 python-python-sphinx-contribspelling  python-websocket-client
python-dateutil                       python-msgpack                        python-pyudev                         python-websockets
python-dictdiffer                     python-multidict                      python-pyxattr                        python-webtest
python-dpkt                           python-mypy                           python-pyxdg                          python-werkzeug
python-dulwich                        python-myst-parser                    python-rdflib                         python-wheel
python-elementpath                    python-nbclient                       python-requests                       python-wrapt
python-evdev                          python-nbformat                       python-requests-mock                  python-WSGIProxy2
python-execnet                        python-netaddr                        python-requests_toolbelt              python-wsproto
python-faker                          python-nose2                          python-rsa                            python-xmlschema
python-fields                         python-notebook                       python-rst.linker                     python-yamlloader
python-flask                          python-olefile                        python-semantic-version               python-yarl
python-flask-sqlalchemy               python-openstackdocstheme             python-service-identity               python-zeroconf
python-flit                           python-outcome                        python-smartypants                    python-zipp
python-fonttools                      python-paramiko                       python-smmap.tex                      python-zope-event
python-gcovr                          python-parso                          python-sniffio
python-gidocgen                       python-parver                         python-sphinxcontrib-asyncio
python-gitdb                          python-paste                          python-sphinxcontrib-autoprogram
[tkloczko@barrel SPECS]$ rpm -qa python-\* | wc -l
513
WARNING: Missing key 'towncrier' in file /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/pyproject.toml

This doesn't seem to be happening on master as executed with the supported methods.

Which one version of the sphinx you are using? I'm usimg 4.0.2.