#28649 closed defect (fixed)

Provide an example destination URL

Reported by: teor Owned by:
Priority: Medium Milestone: sbws: 1.0.x-final
Component: Core Tor/sbws Version:
Severity: Normal Keywords:
Cc: juga, teor Actual Points:
Parent ID: Points:
Reviewer: nickm Sponsor:

Description

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
  • man_sbws.ini.rst , but I couldn't work out what needs to go in the minimal sbws.ini
  • an example config.ini, but there isn't one

Please:

  • add an example URL to config.default.ini, or
  • add a config.ini with an example URL

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

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

Child Tickets

Change History (6)

comment:1 in reply to:  description ; Changed 11 months ago by juga

Replying to 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?:

  • 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.

comment:2 in reply to:  1 Changed 11 months ago by teor

Replying to juga:

Replying to 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?:

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.

comment:3 Changed 11 months ago by juga

Status: newneeds_review

comment:4 Changed 11 months ago by dgoulet

Reviewer: nickm

comment:5 Changed 10 months ago by nickm

Status: needs_reviewmerge_ready

LGTM

comment:6 Changed 10 months ago by juga

Resolution: fixed
Status: merge_readyclosed

Solved conflicts. Changed Debian to system package. Merged

Note: See TracTickets for help on using tickets.