openreferral
Readthedocs vs privately hosted sphinxdocs for documentation builds
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:
- initial migration
- labour time to manage the server and software versioning
- server costs of the infrastructure
- Ensuring we can trigger builds via CI/CD processes like we do now
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!
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: @.***>
Within #449 I am implementing some manual version banners as the automatically generated ones don't seem to be working anyway. Unless there are other reasons to consider moving away from RTD I'd be inclined to close this ticket
