Comments (6)
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.
Related Issues (11)
- Show logging levels of handlers HOT 6
- Exception if formatter doesn't have a _fmt attribute HOT 2
- Overridden parent loggers HOT 7
- document what broken .parent means, and how to fix it HOT 5
- Failing tests on python-3.3 HOT 3
- Python 3.8 support HOT 1
- This should be part of corelibrary logging HOT 3
- Tag the source HOT 1
- Document symbol for propagate HOT 2
- FR: Show if the logging level is delegated or not HOT 5
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from logging_tree.