#28648 closed defect (fixed)

Broken links in DEPLOY.rst

Reported by: teor Owned by: juga
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

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.

Child Tickets

Change History (12)

comment:1 Changed 11 months ago by teor

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

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

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

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

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.

comment:4 in reply to:  2 Changed 11 months ago by juga

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.

comment:5 Changed 11 months ago by teor

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

comment:6 Changed 11 months ago by juga

Owner: set to juga
Status: newaccepted

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.

comment:7 Changed 11 months ago by juga

Regarding linkcheck, i created #28670

comment:8 Changed 11 months ago by juga

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

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

comment:9 Changed 11 months ago by juga

Status: acceptedneeds_review

Now pass the tests, seems travis was being slower

comment:10 Changed 11 months ago by dgoulet

Reviewer: nickm

comment:11 Changed 11 months ago by nickm

Status: needs_reviewmerge_ready

LGTM

comment:12 Changed 11 months ago by juga

Resolution: fixed
Status: merge_readyclosed

Merged

Note: See TracTickets for help on using tickets.