[tor-bugs] #28649 [Core Tor/sbws]: Provide an example destination URL

[Tor Bug Tracker & Wiki]

#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 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?.
 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`).


 > * 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

 > * 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:
 > * add an example URL to config.default.ini, or
 > * add a config.ini with an example URL

 Commented above
 >
 > Please also:
 > * clearly document the minimal sbws.ini in DEPLOY.rst, and
 > * clearly document the minimal sbws.ini at the top of man_sbws.ini.rst
 > * tell me I shouldn't change the other options listed in
 man_sbws.ini.rst

 Commented above

 > This ticket is required for sbws setup, so it should go in sbws 1.0.

--
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/28649#comment:1>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online