Adding documentation about logging_tree HOT 6 CLOSED

The documentation is kept inside of the package, so that the Python help() function, pydoc, and user editor IDE environments can all access it live while people are coding:

https://github.com/brandon-rhodes/logging_tree/blob/master/logging_tree/__init__.py

Is there information in the blog post that you feel is missing from this inline documentation? If so then I will be happy to add it!

from logging_tree.

Again: could you outline what is lacking in the project’s current documentation? I am happy to add material to the documentation so that it is complete and so that people have a great experience when they use the package. I am also happy to discuss whether the documentation — which is currently available both inline on the PyPI page, and also available to an IDE because it lives inside of the docstring of the package’s __init__.py — should live in some third place beyond just PyPI (which serves people who want documentation in their web browser) and __init__.py (which serves people using live IDE tools). But I would like to know what third, new audience is lacking access to the documentation before making the package any more complicated. Could you offer some further comments about what you want to accomplish?

from logging_tree.

It is not uncommon for projects that have documentation (either as Python docstrings, text/.rst/.md files, or a combination of them) that can be built by Sphinx to include a docs/ directory with a conf.py file so that any user or new contributor that fetches the source package is able to build a local, browsable, copy of the documentation.

In distributions like Debian and Ubuntu maintainers tend to build the Sphinx-based documentation to provide the users with a locally browsable copy. (Mostly for access speed or for users with intermittent Internet access)
E.g. the source package "python-bottle" generates a binary package containing the library and another package containing the docs: http://packages.debian.org/source/sid/python-bottle

I'm not asking you to write new documentation, just add the docs/ directory. Anyway, if you prefer not to do so it's not a problem at all! (I can do the build in the Debian package anyway by patching-in the docs/ dir)

from logging_tree.

Thank you for your patient answer! I think I understand: rst text inside of a docstring is accessible both to programmers who open the file, and also to programmers using IDEs that display documentation, but not to Debian users who are accustomed to looking at /usr/share/doc/ to learn how to use something they have installed.

I am not familiar with the techniques used by Debian packagers, so let me ask: is there a simpler tool than Sphinx for converting a docstring to something appropriate for a text file? I have used both "pydoc" and the docutils before on projects that needed simple single-page documentation; I usually only pull Sphinx out when things like cross-references are needed.

from logging_tree.

I'll all some documentation building scripts in the package in future.
In the meantime, the package entered Debian Unstable and will land in Testing soon: https://packages.debian.org/sid/python-logging-tree

from logging_tree.

Wonderful — thank you so much for helping make logging_tree available to more users! I will close this issue now, but please do not hesitate to open any new issues if you run across other problems when trying to keep this packaged for Debian.

from logging_tree.