1.9.7: sphinx documentation support removed???

[kloczek]

I'm really surprised to see that just released 1.9.7 has removed sphinx support (all files has been renamed to .d and docs/copy.py has been removed). Previously it was possible to generate for example man man page for module using python setup.py build_sphinx -b man (I've been using that in my rpm/Solaris IPS packaging procedure).

How can I generate that man page for new version?

Sphinx is de facto standard of the documentation for python modules. More than 70% all modules which I have packaged (almost 600) has documentation and probably ~98% is using sphinx.

[kbandla]

ACK, let us look into what can be done.

[brifordwylie]

Sure, we can add the sphinx build back in... wasn't aware that folks were using it...

[kloczek]

Please .. and thank you for understanding :)

I can show you some small example from my stystem with generating modules documentation a s man pages

[tkloczko@barrel SPECS]$ man python-<tab><tab>
Display all 247 possibilities? (y or n)
python-amqp                               python-hpack                              python-pathspec                           python-sos
python-anyiodoc                           python-httplib2                           python-pillow                             python-sphinx-argparse
python-anytree                            python-hypercorn                          python-platformdirs                       python-sphinx-click
python-argcomplete                        python-hyperframe                         python-pluggy                             python-sphinxcontrib-asyncio
python-arrow                              python-hyperlink                          python-polib                              python-sphinxcontrib-autoprogram
python-asgi                               python-hypothesis                         python-prb                                python-sphinxcontrib-bibtex
python-aspectlib                          python-ifaddr                             python-priority                           python-sphinxcontrib-httpdomain
python-astor                              python-importlib-metadata                 python-productmd-compose                  python-sphinxcontrib-programoutput
python-astroid                            python-inflect                            python-productmd-composeinfo              python-sphinxcontrib-trio
python-async_generator                    python-ipykernel                          python-productmd-discinfo                 python-sphinxcopybutton
python-atomicwrites                       python-ipythonparallel                    python-productmd-images                   python-sphinxext-opengraph
python-attrs                              python-itsdangerous                       python-productmd-rpms                     python-sphinx-inline-tabs
python-augeas                             python-jaraco-classes                     python-productmd-terminology              python-sphinx-removed-in
python-autodocsumm                        python-jaraco-collections                 python-productmd-treeinfo                 python-sphinx_rtd_theme
python-babel                              python-jaraco-envs                        python-prompt_toolkit                     python-sphinx-tabs
python-backcall                           python-jaraco-functools                   python-ptyprocess                         python-sphinx-typlog-theme
python-backports.entry-points-selectable  python-jaraco.itertools                   python-purl                               python-sphobjinv
python-benchmark                          python-jaraco-packaging                   python-py                                 python-sqlparse
python-betamax                            python-jaraco-path                        python-pyasn1                             python-stdlib-list
python-billiard                           python-jaraco-text                        python-pybtex                             python-stem
python-bleach                             python-jedi                               python-pybtex-docutils                    python-sure
python-blinker                            python-Jinja                              python-pycodestyle                        python-sybil
python-boto3                              python-jinja2_pluralize                   python-pydocstyle                         python-systemd
python-botocore                           python-jmespath                           python-pyfakefs                           python-tempora
python-bottle                             python-jupyter_client                     python-pyftpdlib                          python-terminado
python-breathe                            python-jupyter_core                       python-pygal                              python-testpath
python-build                              python-jupytext                           python-pygments                           python-test_server
python-cachetools                         python-kiwi                               python-pyhamcrest                         python-testtools
python-cffi                               python-kombu                              python-pylama                             python-tidy
python-characteristic                     python-lark                               python-pylint                             python-tinycss2
python-chardet                            python-latexcodec                         python-pymeeus                            python-tornado
python-cheroot                            python-lazy-object-proxy                  python-pynacl                             python-traitlets
python-click                              python-libevdev                           python-pyopenssl                          python-transaction
python-click-log                          python-linkify-it-py                      python-pyrad                              python-trio
python-contextlib2                        python-lockfile                           python-pyrsistent                         python-trustme
python-convertdate                        python-lxml                               python-pyscss                             python-twisted
python-coveragepy                         python-mako                               python-pytest                             python-uritemplate
python-coveralls                          python-markupsafe                         python-pytest-checkdocs                   python-urllib3
python-cppy                               python-mdit-py-plugins                    python-pytest-cov                         python-validators
python-cssselect2                         python-metaextract                        python-pytest-regressions                 python-vine
python-cython                             python-mistune                            python-pytest-runner                      python-virtualenv
python-dateutil                           python-mock                               python-pytest-trio                        python-waitress
python-dictdiffer                         python-more-itertools                     python-pytest-xprocess                    python-wcwidth
python-dpkt                               python-msgpack                            python-python-sphinx-contribspelling      python-webcolors
python-dulwich                            python-multidict                          python-pyudev                             python-webencodings
python-elementpath                        python-mypy                               python-pyxattr                            python-webob
python-evdev                              python-myst-parser                        python-pyxdg                              python-websocket-client
python-eventlet                           python-nbclient                           python-requests-mock                      python-websockets
python-execnet                            python-nbformat                           python-requests_toolbelt                  python-webtest
python-faker                              python-netaddr                            python-rich                               python-werkzeug
python-fields                             python-nose2                              python-rsa                                python-wheel
python-flake8                             python-notebook                           python-rst.linker                         python-Whoosh
python-flask                              python-numpydoc                           python-scons                              python-wrapt
python-flit                               python-olefile                            python-scripttest                         python-WSGIProxy2
python-fonttools                          python-openstackdocstheme                 python-selenium                           python-wsproto
python-gcovr                              python-outcome                            python-semantic-version                   python-xmlschema
python-gidocgen                           python-paramiko                           python-service-identity                   python-yamlloader
python-gitdb                              python-parso                              python-setuptools                         python-yarl
python-GitPython.tex                      python-parver                             python-six                                python-zeroconf
python-greenlet                           python-paste                              python-smartypants                        python-zipp
python-h2                                 python-paste-deploy                       python-smmap.tex                          python-zope-event
python-hacking                            python-path                               python-sniffio

[brifordwylie]

Part of the context for the change is that we've changed from using RST to Markdown and using github.io to house the new docs: https://kbandla.github.io/dpkt/

I'm assuming that we can have use the markdown docs as Sphinx input (https://www.sphinx-doc.org/en/master/usage/markdown.html)... so I'll try to poke around a bit and see if I can reinstate the 'Sphinx' document build...

[kloczek]

With proper setuptooss<>sphinx integration you can use command like "python3 setup.py build_sphinx -b html --build-dir build/sphinxand after that inbuild/sphinx/html` you will be able to find files which could be transffered to your website.

[brifordwylie]

@kloczek right that's what we had before.. we've moved to Markdown and github.io https://kbandla.github.io/dpkt/ (as stated above)... I get that man pages are nice.. so we'll see what we can do to support the generation of man pages.

[kloczek]

BTW .. I'm not sure do you know but you can use md with sphinx :) https://www.sphinx-doc.org/en/master/usage/markdown.html

[kloczek]

I woiuld really recommend to still keep whole doc source as files under sphinx hood :P (md or any other format .. sphinx can use even doxygen generated files and has few API documentantion generators) https://www.sphinx-doc.org/en/master/usage/extensions/index.html

[obormot]

https://github.com/serra/sphinx-with-markdown