2.6.0: man pages generation warnings #1370
Comments
|
@kloczek I guess this is relevant mostly to package maintainers (.deb, .rpm, etc). Could you show me how you currently try to build this if you have a package repo somewhere? I suppose it's like this: If we want to clean this up, we will probably want to add this to tox, add a CI linter check and maybe a pre-commit hook, to keep manpages clean in the future. |
|
Yes I'm packaging python-gitlab into rpm package.
I'm not sure is it necessary but may be useful to keep an eye on the documentation generation process in CI :) Generally speaking I've stared moving away in my python packages from html form of the documentation to roff format used by man commad. I've started even putting all python modules man pages on lvl3 and renaming those man pages from [tkloczko@barrel SPECS]$ man python-<tab><tab>
Display all 110 possibilities? (y or n)
python-amqp python-flask python-netaddr python-pynacl python-sphinx-removed-in
python-anytree python-fonttools python-nose2 python-pyopenssl python-sphinx-tabs
python-arrow python-gcovr python-openstackdocstheme python-pyrad python-sphinx-typlog-theme
python-asgiref python-gidocgen python-outcome python-pyrsistent python-sphobjinv
python-astor python-gitdb python-paramiko python-pytest python-sqlparse
python-async_generator python-GitPython.tex python-parso python-pytest-cov python-sure
python-attrs python-greenlet python-paste python-pyudev python-testpath
python-babel python-hacking python-path python-rdflib python-tinycss2
python-backcall python-hyperlink python-pluggy python-requests python-tornado
python-betamax python-hypothesis python-polib python-requests_toolbelt python-trio
python-billiard python-itsdangerous python-productmd-compose python-rst.linker python-trustme
python-bottle python-jaraco-envs python-productmd-composeinfo python-semantic-version python-twisted
python-breathe python-jaraco-packaging python-productmd-discinfo python-service_identity python-urllib3
python-cachetools python-jedi python-productmd-images python-smartypants python-vine
python-case python-Jinja python-productmd-rpms python-smmap.tex python-wcwidth
python-cffi python-lark python-productmd-terminology python-sniffio python-webencodings
python-click python-lazy-object-proxy python-productmd-treeinfo python-sphinxcontrib-asyncio python-webtest
python-coveragepy python-libevdev python-ptyprocess python-sphinxcontrib-autoprogram python-wheel
python-curio python-markupsafe python-py python-sphinxcontrib-httpdomain python-Whoosh
python-dpkt python-mistune python-pycodestyle python-sphinx-contribspelling python-wikipedia
python-dulwich python-msgpack python-pygments python-sphinxcontrib-trio python-wrapt
python-evdev python-multidict python-pylint python-sphinx-hoverxref python-WSGIProxy2So to do that for python-gitlab I'm using small patch like below: --- a/docs/conf.py~ 2021-01-29 13:06:10.000000000 +0000
+++ b/docs/conf.py 2021-03-08 11:46:47.501884316 +0000
@@ -256,9 +256,9 @@
(
"index",
"python-gitlab",
- "python-gitlab Documentation",
+ "python-gitlab Python Module Documentation",
["Gauvain Pocentek, Mika Mäenpää"],
- 1,
+ 3,
)
]But that is something which I'm doing on packaging to deliver some consistent usability of that form of the python modules documentation and I would not be asking to commit that to python-gitlab because it is non-generic adjustment :P Nevertheless on process generating roff documentation sometimes I'm able to spot some sphinx warnings which IMO would be good to clean because fixing those warnings may cause improve final form of that type of documentation. |
|
Ok great, thanks a lot for the context! Yes, in that case I'd like it in CI so that you don't have the same problem again in 2.8.0 and so on and on ;) Do you happen to know any other maintainers e.g. for debian-based distros or other? |
No I don't know anything about that. |
|
Ok, I didn't go as far as building with the |
|
Just tested that patch: [tkloczko@barrel SPECS]$ rpmbuild -ba --with check python-gitlab.spec
warning: Downloading https://github.com/python-gitlab/python-gitlab//archive/v2.7.1/python-gitlab-2.7.1.tar.gz to /home/tkloczko/rpmbuild/SOURCES/python-gitlab-2.7.1.tar.gz
warning: Downloading https://github.com/python-gitlab/python-gitlab//commit/cbd4d52b.patch#/python-gitlab-docs-fail-on-warnings-during-sphinx-build.patch to /home/tkloczko/rpmbuild/SOURCES/python-gitlab-docs-fail-on-warnings-during-sphinx-build.patch
error: patch 0 defined multiple times
[tkloczko@barrel SPECS]$ rpmbuild -ba --with check python-gitlab.spec
Executing(%prep): /bin/sh -e /var/tmp/rpm-tmp.5ECrk2
+ umask 022
+ cd /home/tkloczko/rpmbuild/BUILD
+ cd /home/tkloczko/rpmbuild/BUILD
+ rm -rf python-gitlab-2.7.1
+ /usr/bin/gzip -dc /home/tkloczko/rpmbuild/SOURCES/python-gitlab-2.7.1.tar.gz
+ /usr/bin/tar -xof -
+ STATUS=0
+ '[' 0 -ne 0 ']'
+ cd python-gitlab-2.7.1
+ /usr/bin/chmod -Rf a+rX,u+w,g-w,o-w .
+ /usr/bin/cat /home/tkloczko/rpmbuild/SOURCES/python-gitlab-man3_level.patch
+ /usr/bin/patch -p1 -s --fuzz=0 --no-backup-if-mismatch
+ /usr/bin/cat /home/tkloczko/rpmbuild/SOURCES/python-gitlab-docs-fail-on-warnings-during-sphinx-build.patch
+ /usr/bin/patch -p1 -s --fuzz=0 --no-backup-if-mismatch
+ RPM_EC=0
++ jobs -p
+ exit 0
Executing(%build): /bin/sh -e /var/tmp/rpm-tmp.ylEbDs
+ umask 022
+ cd /home/tkloczko/rpmbuild/BUILD
[..]
+ PYTHONPATH=/home/tkloczko/rpmbuild/BUILD/python-gitlab-2.7.1
+ sphinx-build -b man -d python-gitlab docs .
Running Sphinx v3.5.3
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 62 added, 0 changed, 0 removed
reading sources... [100%] switching-to-v4
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-gitlab.3 { install cli-usage api-usage faq api-objects gl_objects/access_requests gl_objects/appearance gl_objects/applications gl_objects/emojis gl_objects/badges gl_objects/branches gl_objects/clusters gl_objects/messages gl_objects/commits gl_objects/deploy_keys gl_objects/deploy_tokens gl_objects/deployments gl_objects/discussions gl_objects/environments gl_objects/events gl_objects/epics gl_objects/features gl_objects/geo_nodes gl_objects/groups gl_objects/issues gl_objects/boards gl_objects/labels gl_objects/notifications gl_objects/mrs gl_objects/mr_approvals gl_objects/milestones gl_objects/namespaces gl_objects/notes gl_objects/packages gl_objects/pagesdomains gl_objects/personal_access_tokens gl_objects/pipelines_and_jobs gl_objects/projects gl_objects/project_access_tokens gl_objects/protected_branches gl_objects/releases gl_objects/runners gl_objects/remote_mirrors gl_objects/repositories gl_objects/repository_tags gl_objects/search gl_objects/settings gl_objects/snippets gl_objects/system_hooks gl_objects/templates gl_objects/todos gl_objects/users gl_objects/variables gl_objects/sidekiq gl_objects/wikis api/gitlab api/gitlab.v4 cli-objects release_notes changelog switching-to-v4 } done
build succeeded.No warnings at all :P Thank you very much :) |
The text was updated successfully, but these errors were encountered: