#28649: Provide an example destination URL ---------------------------+----------------------------------- Reporter: teor | Owner: (none) Type: defect | Status: new Priority: Medium | Milestone: sbws: 1.0.x-final Component: Core Tor/sbws | Version: Severity: Normal | Resolution: Keywords: | Actual Points: Parent ID: | Points: Reviewer: | Sponsor: ---------------------------+-----------------------------------
Comment (by teor): Replying to [comment:1 juga]: > Replying to [ticket:28649 teor]: > > When I tried to work out how to configure a sbws destination, I looked at: > > * DEPLOY.rst, but the links were broken (#28648) > > * config.default.ini, but the [destinations] section didn't tell me what I needed to add > > It's not expected that a user would look at this file. What made you think you should look there?. There is no config.ini anywhere, so I looked for similar files. > That file is providing the defaults, but the user should never change it, otherwise it'll give conflicts when the user update sbws. > There could be an example URL commented, but the user wouldn't see it. > Actually i think that instead of having that file, we should have all those defaults in `globals.py` and maybe allow the user to change them via a user config file (`~/.sbws.ini` or `/etc/sbws/sbws.ini`). Ok, please open a ticket in sbws: unspecified, unless you think this refactor is urgent. > > * man_sbws.ini.rst , but I couldn't work out what needs to go in the minimal sbws.ini > > How could i make this lines more clear?: > - https://gitweb.torproject.org/sbws.git/tree/docs/source/man_sbws.ini.rst#n9 > - https://gitweb.torproject.org/sbws.git/tree/docs/source/man_sbws.ini.rst#n68 > - https://gitweb.torproject.org/sbws.git/tree/docs/source/man_sbws.ini.rst#n168 > - https://gitweb.torproject.org/sbws.git/tree/docs/source/man_sbws.ini.rst#n190 Tell users that the destination is mandatory, and put an example destination in DEPLOY.rst. Then users don't have to read and understand the whole man page to set up sbws. > > * an example config.ini, but there isn't one > > There is one: https://gitweb.torproject.org/sbws.git/tree/docs/source/config.example.ini > In the documentation: https://sbws.readthedocs.io/en/latest/config.html#id2 > Then that example should be moved to DEPLOY.rst. > However, it will not be displayed in Github (https://github.com/torproject/sbws/blob/master/docs/source/config.rst) because it's using an Sphinx directive. > Github does not contain the build HTML and i should not make all the links to point to sbws.rtfd.io, because then the locally build documentation would need Internet. > See my comment about this in https://trac.torproject.org/projects/tor/ticket/28648#comment:4 Please link to the example file from DEPLOY.rst, even if the link only works on read the docs. -- Ticket URL: <https://trac.torproject.org/projects/tor/ticket/28649#comment:2> Tor Bug Tracker & Wiki <https://trac.torproject.org/> The Tor Project: anonymity online
_______________________________________________ tor-bugs mailing list tor-bugs@lists.torproject.org https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-bugs