Broken links in DEPLOY.rst

These links are broken on GitHub:

To configure destinations, create a configuration file according to ./docs/source/man_sbws.ini.rst (or /docs/source/man_sbws.ini.rst or :doc:`man_sbws.ini` or man sbws.ini)

https://github.com/torproject/sbws/blob/master/DEPLOY.rst#scanner-setup

We should fix this before sbws is deployed by more operators.

changed milestone to %sbws: 1.0.x-final

added component::core tor/sbws milestone::sbws: 1.0.x-final owner::juga priority::medium resolution::fixed reviewer::nickm severity::normal status::closed type::defect labels

Is there an automatic link-checking tool you can use when building sbws in CI?

Replying to teor:

These links are broken on GitHub:

{{{ To configure destinations, create a configuration file according to ./docs/source/man_sbws.ini.rst (or /docs/source/man_sbws.ini.rst or :doc:man_sbws.ini or man sbws.ini) }}}

https://github.com/torproject/sbws/blob/master/DEPLOY.rst#scanner-setup

You get this URL from :doc:man_sbws.ini in Github, because it's a Sphinx directive. It's correctly interpreted in https://sbws.readthedocs.io/en/latest/DEPLOY.html or when you build the documentation locally and open it in a browser as file:///.../sbws/docs/build/html/DEPLOY.html

The link /docs/source/man_sbws.rst <man_sbws>_ is wrong, it should be <man_sbws.html>_ and this would work both in Githab and rtfd.

I tried to cover all the possible ways one could read the documentation from, which are:

1. rst source files (no Internet, not build documentation): /docs/source/X.rst
2. Github: interpret rst, but not Sphinx references: <X.html>_
3. rtfd and locally build documentation: interpret Sphinx references and rst: :doc:X

3 is not needed and i need to fix 2

Replying to teor:

Is there an automatic link-checking tool you can use when building sbws in CI?

There's linkcheck (https://github.com/torproject/sbws/blob/master/tox.ini#L86), commented because that would require Internet for the tests. It can be call in Travis.

However, that would give errors as:

line    5) redirect  http://keepachangelog.com/en/1.0.0/ - permanently to https://keepachangelog.com/en/1.0.0/

Which we should change to https, will open other ticket for that.

Or :

(line   88) broken    https://docs.python-requests.org/ - HTTPSConnectionPool(host='docs.python-requests.org', port=443): Max retries exceeded with url: / (Caused by SSLError(CertificateError("hostname 'docs.python-requests.org' doesn't match either of '*.readthedocs.org', 'readthedocs.org'",),))

It seems there is not option to disable checking certificates (http://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder)

There is also the option nitpicky (http://www.sphinx-doc.org/en/master/usage/configuration.html#confval-nitpicky), but it only checks Sphinx references.

Replying to juga: [...]

I tried to cover all the possible ways one could read the documentation from, which are:

1. rst source files (no Internet, not build documentation): /docs/source/X.rst
2. Github: interpret rst, but not Sphinx references: <X.html>_
3. rtfd and locally build documentation: interpret Sphinx references and rst: :doc:X

3 is not needed and i need to fix 2

All the other sphinx directives, would be also broken when reading the docs in Github, like :term:scanner (interpreted as docs/glossary.html#term-scanner in rtfd) If we want that the docs can be read in Github, i'd need to stop using Sphinx directives and remove all of them. Maybe there should be warning instead saying to look the documentation in rtfd?. There's the Debian package sbws-doc, which includes the html pages generated by Sphinx, in which the directives are correctly interpreted.

Ok, seems complicated. Do whatever you think is best.

ok, i'll add a warning that they should be read in rtfd.io or locally build. I'll try to make it compatible with Github when possible.

Trac:
Status: new to accepted
Owner: N/A to juga

Regarding linkcheck, i created #28670 (moved)

https://github.com/torproject/sbws/pull/301

It seems the deb.tpo trusty release today makes stem fail and therefore also the tests.

Now pass the tests, seems travis was being slower

Trac:
Status: accepted to needs_review

Trac:
Reviewer: N/A to nickm

LGTM

Trac:
Status: needs_review to merge_ready

Merged

Trac:
Resolution: N/A to fixed
Status: merge_ready to closed

closed

mentioned in issue #28649 (moved)

moved to tpo/network-health/sbws#28648 (closed)

mentioned in issue tpo/network-health/sbws#28649 (closed)