pudb
pudb copied to clipboard
inducer
Settings doc
Added new doc section about pudb configuration with list of available config option. Mostly copy-pasted help text for options from settings.py.
Thanks for your contribution! I'm not sure I would like to have the config file documented, since that makes evolving it substantially harder, because there's documented behavior with which we'd have to retain backwards compatibility...
I guess that came from the discussion at https://github.com/inducer/pudb/pull/246 whether to add a setting to the UI. If we want to keep the file location undocumented then we should keep all the settings in the UI.
I guess that came from the discussion at #246
Right. I haven't found any suitable place to mention the new setting in the docs. And additionally, I thought it would be much more convenient to list all settings in the docs.
I'm not sure I would like to have the config file documented, since that makes evolving it substantially harder ... we'd have to retain backwards compatibility
Actually, yes. But we already have to. Users already can tune some settings and new versions will have to deal with that legacy (the same is applicable for changing the theme format). I think there could be some deprecation mechanisms. And also, it forces us to pay more attention to changelog (and mention any deprecations there). Additionally this is a good point to generate versioned docs. Tornado for example has docs for several versions: last stable and quite old 3.2 branch.
I also think, that it's just the first step for settings doc. Ideally this kind of doc should be generated from the code (like uWSGI project does)
Pudb is an application, not a library, so that sort of thing is a lot less important for it.
Hi there. I've updated config doc. I've removed such inner settings like sidebar_width.
I've slightly fixed the configuration text and options order (to be consistent with the configuration dialog).
Thanks for your contribution. This needs extensive proofreading before it's ready to merge. Also please stick to AE conventions for consistency. Please use ReST roles as documented with Sphinx.
AE conventions for consistency
Sorry, I'm not familiar with that conventions. Could you give me a link where I can read about that conventions?
Please use ReST roles as documented with Sphinx.
Do you mean use of double backquotes for setting name (like ``line_numbers``) is not a good idea and I should use some of sphinx domains?
Sorry, I'm not familiar with that conventions
https://en.wikipedia.org/wiki/American_English
Do you mean use of double backquotes for setting name (like
line_numbers) is not a good idea
E.g.
:file:`xyz.txt`
https://en.wikipedia.org/wiki/Comparison_of_American_and_British_English specifically.
@inducer thanks for links. English is not native language for me. So I definitely agree with you:
This needs extensive proofreading before it's ready to merge.
I still don't get notice about ReST roles. The only file links in the doc are pudb.cfg paths. Should I use file role for that case instead of code role?