RFE: please restore sphinx suppoer

[kloczek]

It is possible to restore conf.py files? 🤔

It looks like with latest version documentation renderer has been changed from sphinx to mkdoc. On packaging modules I'm using sphinx to build roff output AKA man page wuch is still most popular documentation format on all Unix platforms. Sphinx can use as source .md files as well and mkdoc is able to generate only html 😞 I have now packaged now

[tkloczko@pers-jacek SPECS]$ ls -1 python-*.spec |wc -l
1249

and in that population I was able to generate and package documentation as man page for:

[tkloczko@pers-jacek SPECS]$ grep %sphinx_build_man python-*.spec |wc -l
704

which is more than half of all packaged modules. For the contrast in that almost 1.25k population of the packaged python modules mkdoc uses currently only:

python-dirty-equals.spec:# TODO: uses mkdoc -> add sphinx support
python-fasteners.spec:# TODO: sphinx replaced by mkdoc https://github.com/harlowja/fasteners/issues/92
python-fasteners.spec:# TODO: uses mkdoc -> move back doc to sphinx (0.17.3 has conf.py)
python-hishel.spec:# TODO: uses mkdoc
python-httpcore.spec:# TODO: uses mkdoc. Sphinx has been removed and old conf.py can be retrieved from git
python-httpx.spec:# TODO: uses mkdoc
python-pdm.spec:# TODO: uses mkdoc
python-ruff.spec:# TODO: uses mkdoc -> add sphinx support
python-starlette.spec:# TODO: package uses mkdoc
python-typer.spec:# TODO: docs/ used mkdocs
python-uvicorn.spec:# TODO: uses mkdoc -> add sphinx conf.py to allow generate man page

which is less than 1%.

mkcoc support can coexist with sphinx.

[kloczek]

Sorry I just fount in those notes that I've already asked you about that.

[psarka]

Yes indeed you have. And you have not explained what is wrong with the method to generate the man page (or any other output supported by pandoc) that I have provided.

[kloczek]

Yes indeed you have. And you have not explained what is wrong with the method to generate the man page (or any other output supported by pandoc) that I have provided.

Where did you provided that method? 🤔

[psarka]

https://github.com/harlowja/fasteners/issues/92#issuecomment-1535694908

[kloczek]

Other way .. would you accept PR with restore conf.py to render document in chosen format out of the same .md files used by mkdoc? 🤔

[psarka]

Well first I'd like to understand what's wrong with the method posted above...

[kloczek]

It is all about standardisation.

[psarka]

To my knowledge there is no standard mandating or even suggesting that python package docs are compatible with Sphinx. So I'm reading you answer as "there is nothing wrong with the method to render docs, but it is different from 99% of packages that I'm using and it is a burden for me to adapt to it".

If my reading is correct, then my reply is no, I will not accept a PR with conf.py, as sphinx compatibility is not important to the users of fasteners library (you were the only one to care for this). So I will ask you to adapt to fasteners instead.

[kloczek]

To my knowledge there is no standard mandating or even suggesting that python package docs are compatible with Sphinx.

Will show you stats from distro: on which I'm working

[tkloczko@pers-jacek SPECS]$ ls -1 python-*.spec | wc -l; grep %sphinx_build_man python-*.spec | wc -l
1243
700

On top of that 11 modules from that population uses mkdoc and 2-3 from those 700 is possible to generate documentation using mkdoc and sphinx. Almost 400 remaining have documentation consisting only out single README.* file

[tkloczko@pers-jacek SPECS]$ grep -l "%doc README.*$" python-*.spec | wc -l
393

In last years I'm observing that content of those README.* files time to time is converted to full doc .. in all cases AFIK it mas migration to sphinx (5-7 each year). Everything else has more than one file in .md. .rst and plain ascii.

As as you wrote there is no de jure standard however as you may see it is kind of de facto standard. I'm not asking to remove mkdoc support (which you like/prefer). I'm asking for possibility to generate documentation using sphinx as well .. which offers 15 or 16 output formats which is matter of adding one conf.py file.

Example .. do you have in your documentation links to another modules docs? Sphinx offers automatic update those links and verification of those connections on render-time ..