Generate non-HTML (man page) docs (with sphinx)

[kloczek]

Looks like docs/conf.py file has been removed. Is it any particular reason why this has been done? 🤔

[jfhbrook]

Yup, I switched to mkdocs!

[kloczek]

Yup, I switched to mkdocs!

mdtool allows only generate htlm. Sphinx allows render 16 output formats. On packaging python modules I'm generating documentation as man pages

[tkloczko@pers-jacek SPECS]$ grep %pyproject_wheel -l *.spec|wc -l; grep -l %sphinx_build_man *.spec|wc -l
1250
677

Above means that I have +1.2k packages with python modules and in case of +half is possible to generate sphinx dokumentatorom. Amongst all those module only less than 10 uses mkdoc.

Is it possible to restore conf.py file? Sphinx can process .md files ass well so there is no collision between those two documentation generators.

[jfhbrook]

I believe there are enough minor differences that I wouldn't be able to naively bring back the conf file and have it working or feel comfortable supporting it. I'm not against it, however I don't have the time to set it up and QA it myself.

That said, if you want to send a PR that adds a conf.py file and generates non-HTML docs with sphinx, I'm happy to review/merge/release. I can maintain the feature, I just don't have the bandwidth to implement it.

[kloczek]

Thank you very much for understanding👍 😄

Nevertheless I'm a bit surprised because in recent years I found less than 10 project which have mkdoc support. Most of them have sphinx support as well. Sphinx is de facto kind of python standard. Number of sphinx extensions and themes is really gigantic compare to mkdoc. Sphinx as well is very actively developed.

OK will have look on that.

[jfhbrook]

Yeah, totally. I appreciated the improved markdown support and the yaml-based config, and RTD has good support for it. But I hear where you're coming from!

I know I said I was pressed for time, but I happen to be taking time off and can probably take a brief peek this afternoon. If it's an easy lift I can fix; if not, I'll at least have some lessons to share.

[jfhbrook]

As you can see from the merged PR, I used sphinx to generate a very basic man page. It's nowhere near as comprehensive as the full documentation, but it should at least get you something.

I'm closing this, since we now have a man page and I don't intend to fully switch back from mkdocs. Sorry to be disappointing - I just like mkdocs much better and switching was a relatively large lift. Maybe someday if mkdocs ultimately disappoints, but not now.

[kloczek]

Thank you very much for your time. I'm really appreciated for what you've done 👍 😄 Here is the result with generated man page:

PYTHON-PYEE(3)                                                                            pyee                                                                            PYTHON-PYEE(3)

NAME
       python-pyee - pyee Python Module Documentation

       pyee is a rough port of node.js's EventEmitter. Unlike its namesake, it includes a number of subclasses useful for implementing async and threaded programming in python, such as
       async/await as seen in python 3.5+.

INSTALL
       You can install this project into your environment of choice using pip:

          pip install pyee

USAGE
       pyee supplies a EventEmitter class that is similar to the EventEmitter class from Node.js. In addition, it supplies subclasses for asyncio, twisted, concurrent.futures and trio,
       as supported by the environment.

EXAMPLE
          In [1]: from pyee.base import EventEmitter

          In [2]: ee = EventEmitter()

          In [3]: @ee.on('event')
             ...: def event_handler():
             ...:     print('BANG BANG')
             ...:

          In [4]: ee.emit('event')
          BANG BANG

          In [5]:

API
       pyee contains a number of modules, each intended for a different concurrency paradigm or framework:

       • pyee - synchronous EventEmitter, like Node.js

       • pyee.asyncio - asyncio support

       • pyee.twisted - twisted support

       • pyee.executor - concurrent.futures support

       • pyee.trio - trio support

       In addition, it contains two experimental modules:

       • pyee.uplift - support for "uplifting" event emitters from one paradigm to another - ie., adopting synchronous event emitters for use with asyncio

       • pyee.cls - support for "evented classes", which call class methods on events

       For in-depth API documentation, visit the docs on readthedocs.io.

LINKS
       • Fork Me On GitHub!

       • The Docs on readthedocs.io

AUTHOR
       Josh Holbrook

COPYRIGHT
       2023, Josh Holbrook

                                                                                      Nov 23, 2023                                                                        PYTHON-PYEE(3)

Man page is not pyee but python-pyee because I'm putting all python modules man pages under name python-<modulename> to be able easy access to any python modules documentation using man command like below

[tkloczko@pers-jacek SPECS]$ man python-<tab><tab>
python-pyee                    python-markupsafe              python-sniffio
python-automat                 python-outcome                 python-sortedcontainers
python-babel                   python-pluggy                  python-sphinx
python-build                   python-pygments                python-sphinx-theme-alabaster
python-charset-normalizer      python-pyproject-hooks         python-trio
python-constantly              python-pytest                  python-twisted
python-dateutil                python-pytest-asyncio          python-urllib3
python-hyperlink               python-pytest-trio             python-wheel
python-importlib-metadata      python-requests                python-zipp
python-installer               python-setuptools              python-zope-event
python-jinja2                  python-six                     python-zopeinterface

[jfhbrook]

Yeah, that makes a lot of sense.

Are you publishing these builds anywhere? COPR or something?

[kloczek]

I'm working on my own dystrybutorom which still is not publicly available because few things needs to be finished.

[jfhbrook]

Word, that sounds cool!