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