Settings doc #252
Settings doc #252
Conversation
|
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... |
|
@asmeurer, opinions? |
doc/configuration.rst
Outdated
| Configuration | ||
| ------------- | ||
|
|
||
| PuDB uses configuration file is located at ``~/.config/pudb/pudb.cfg``. |
There was a problem hiding this comment.
The actual location is based on the XDG logic at the top of settings.py.
There was a problem hiding this comment.
Thanks. Added corrections there.
|
I guess that came from the discussion at #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. |
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.
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. |
doc/configuration.rst
Outdated
|
|
||
| Show or hide the line numbers in the source code pane. | ||
|
|
||
| sidebar_width |
There was a problem hiding this comment.
I don't think these should be documented. Plus the text you have here isn't very helpful anyway.
There was a problem hiding this comment.
I agree with you. But before I update this PR I'd like to understand if has any chance to be merged.
@inducer are you strictly against of merging this PR or we can discuss and polish these changes to get them merged?
There was a problem hiding this comment.
We can merge it. But I'm not enamored with the content--so if it falls too far out of date at some point in the future, I may just delete it.
There was a problem hiding this comment.
I have an idea to make it autogeneratable for the next step. So it wouldn't get out of date.
|
Hi there. I've updated config doc. I've removed such inner settings like |
| @@ -0,0 +1,87 @@ | |||
| Configuration | |||
| ------------- | |||
|
|
|||
There was a problem hiding this comment.
It should state at the top that you can change the settings within PuDB by pressing Ctrl-p. That's the most important thing here (and it isn't obvious to everyone).
There was a problem hiding this comment.
Did you push? I don't see it.
There was a problem hiding this comment.
Sorry. Something went wrong. Pushed it.
|
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. |
Sorry, I'm not familiar with that conventions. Could you give me a link where I can read about that conventions?
Do you mean use of double backquotes for setting name (like |
https://en.wikipedia.org/wiki/American_English
E.g. |
|
@inducer thanks for links. English is not native language for me. So I definitely agree with you:
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? |
Added new doc section about pudb configuration with list of available config option. Mostly copy-pasted help text for options from
settings.py.