search

openreferral / specification

The Human Services Data Specification - a data exchange format developed by the Open Referral Initiative
https://openreferral.org
Other
117 stars 49 forks source link

Readthedocs vs privately hosted sphinxdocs for documentation builds #490

Open mrshll1001 opened 6 months ago

mrshll1001 commented 6 months ago

We currently host our documentation on readthedocs, which is an instance of sphinxdocs.

448 flags that some behaviours (ie redirections for older versions) throw up some error pages which may be confusing for some, and a workaround would be very convoluted on the current hosted platform. One way around this is to migrate away to a privately hosted sphinxdocs instance, with greater control over the plugins and environment.

We would need to consider:

robredpath commented 5 months ago

We would also need to consider the cost associated with re-implementing RTD features, and/or maintaining a fork of RTD's open-source stack. A lot of work has gone into making RTD what it is!

And then, there's also the cost of implementing the new redirect mechanism, whatever that is.

It looks like some of the issues in #448 have been caused by (intentionally or otherwise) switching off Clean URLs - see https://docs.readthedocs.io/en/stable/user-defined-redirects.html#clean-html-urls-redirects for more on that in a redirect context.

Work on SEO and the issue of old versions of docs appearing in search results is something that we're looking into at the moment for IATI; we'll share whatever we find when we've got some ideas!

dan-odsc commented 5 months ago

Thanks Rob!

On Mon, 22 Jan 2024 at 09:24, Rob Redpath @.***> wrote:

We would also need to consider the cost associated with re-implementing RTD features, and/or maintaining a fork of RTD's open-source stack https://github.com/readthedocs/readthedocs.org. A lot of work has gone into making RTD what it is!

And then, there's also the cost of implementing the new redirect mechanism, whatever that is.

It looks like some of the issues in #448 https://github.com/openreferral/specification/issues/448 have been caused by (intentionally or otherwise) switching off Clean URLs - see https://docs.readthedocs.io/en/stable/user-defined-redirects.html#clean-html-urls-redirects for more on that in a redirect context.

Work on SEO and the issue of old versions of docs appearing in search results is something that we're looking into at the moment for IATI; we'll share whatever we find when we've got some ideas!

— Reply to this email directly, view it on GitHub https://github.com/openreferral/specification/issues/490#issuecomment-1903577206, or unsubscribe https://github.com/notifications/unsubscribe-auth/A4PEV22FUH73WLFR72TUQULYPYV6VAVCNFSM6AAAAABBU7ICG2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSMBTGU3TOMRQGY . You are receiving this because you are subscribed to this thread.Message ID: @.***>