[10035] Build apidocs inside Read the docs environment.

[adiroiban]

Scope

The result is available here https://twisted--1466.org.readthedocs.build/en/1466/

To simplify the release process we want to host the API docs inside read the docs.

I find that the Read the Docs theme is easier to read than the Twisted Trac theme for Sphinx.

This provides support for creating API docs via both the old bin/admin/build-apidocs and the Read The Docs build.
In this way we can transition with the next release

Followup work

• Update the CI workflow to fail on apidocs + narrative docs errors - https://twistedmatrix.com/trac/ticket/10066
• Remove usage of apilinks and replace with intersphinx. - https://twistedmatrix.com/trac/ticket/10057
• Update Twisted own hosted docs to redirect to read the docs for latest version - In Braid

How to test

Make sure the old script continues to work tox -e apidocs

Check that Sphinx docs now has API docs included in the index this is the before last.

Also check that source links for API work.

tox  -e apidocs
firefox docs/_build/index.html

Check read the docs

Main https://twisted--1466.org.readthedocs.build/en/1466/
API https://twisted--1466.org.readthedocs.build/en/1466/api/index.html

Apilinks https://twisted--1466.org.readthedocs.build/en/1466/core/howto/servers.html link at "Your protocol handling class will usually subclass twisted.internet.protocol.Protocol. "

Contributor Checklist:

• The associated ticket in Trac is here: https://twistedmatrix.com/trac/ticket/10035
• I ran tox -e lint to format my patch to meet the Twisted Coding Standard
• I ran additional checks listed at Getting Your Patch Accepted
• I have created a newsfragment in src/twisted/newsfragments/ (see: News files)
• I have updated the automated tests.
• I have submitted the associated Trac ticket for review by adding the word review to the keywords field in Trac, and putting a link to this PR in the comment; it shows up in https://twisted.reviews/ now.

[adiroiban]

This is ready for review... the deprecated release script is still failing, but that might be a bug in pydoctor.
Those tests were enabled for a very long time.

The result is available here https://twisted--1466.org.readthedocs.build/en/1466/

[graingert]

related, twisted-infra/braid#264

There will be a second PR to redirect twistedmatrix.com/documents/current to the new domain, but first we should have this pushed to PROD and make sure it works and later we can push the redirection.

@adiroiban when we do the redirect there will be no apidocs for any of the older builds

[adiroiban]

My plan is to only redirect "current" URL fragment. Older version docs will continue to be on the same server without redirecting.

Later we can see how we can push to RTD tags to rebuild the docs for very old versions.

We already have some older version on RTD and the have absolute URL to apidocs.

[adiroiban]

This is ready for review. See PR description.

[mthuurne]

Looks good, only some minor comments (typo + formatting).

I don't know much about Sphinx, so I skimmed over most of the conf.py file.

[mthuurne]

Suggested change

	# This should not fail on errors so that we can view the rended Read The Docs.
	# This should not fail on errors so that we can view the rendered Read The Docs

[mthuurne]

Those spaces before ] are probably harmless, but it looks a bit odd.

[graingert]

Suggested change

	# This should not fail on errors so that we can view the rended Read The Docs.
	# pages even on errors.
	# This should not fail on errors so that we can view the rendered Read The Docs.
	# pages even on errors.