Add readthedocs integration example

docs/source/publish-github-action.rst

@@ -5,7 +5,7 @@ Simple GitHub Action to publish API docs
 
 Here is an example of a simple GitHub Action to automatically
 generate your documentation with Pydoctor
-and publish it to your default GitHub Pages website.
+and publish it to your default GitHub Pages website when there is a push on the ``main`` branch.
 
 Just substitute `(projectname)` and `(packagedirectory)`
 with the appropriate information.
@@ -14,23 +14,24 @@ with the appropriate information.
 
     name: apidocs
     on:
-    - push
+      push:
+        branches: [main]
 
     jobs:
       deploy:
         runs-on: ubuntu-latest
 
         steps:
         - uses: actions/checkout@master
-        - name: Set up Python 3.8
+        - name: Set up Python 3.12
           uses: actions/setup-python@v2
           with:
-            python-version: 3.8
+            python-version: 3.12
 
         - name: Install requirements for documentation generation
           run: |
             python -m pip install --upgrade pip setuptools wheel
-            python -m pip install docutils pydoctor
+            python -m pip install pydoctor
 
         - name: Generate API documentation with pydoctor
           run: |

docs/source/publish-readthedocs.rst

@@ -0,0 +1,51 @@
+:orphan:
+
+Simple ReadTheDocs config to publish API docs
+---------------------------------------------
+
+Here is an example of a simple ReadTheDocs integration to automatically
+generate your documentation with Pydoctor. 
+
+.. note:: This kind of integration should
+    not be confused with `Sphinx support <sphinx-integration.html>`_ that can also be used to run 
+    pydoctor inside ReadTheDocs as part of the standard Sphinx build process. 
+
+    This page, on the other hand, documents **how to simply run pydoctor 
+    and publish on ReadTheDocs** by using build customizations features.
+
+This example only includes a configuration file (``.readthedocs.yaml``), 
+but the repository must also have been 
+integrated to ReadTheDocs (by linking your Github account and importing your project for 
+instance or by `manual webhook configuration <https://stackoverflow.com/a/74959815>`_).
+
+The config file below assume you're cloning your repository with http(s) protocol 
+and that repository is a GitHub instance 
+(the value of ``--html-viewsource-base`` could vary depending on your git server). 
+
+Though, a similar process can be applied to Gitea, GitLab, Bitbucket ot others git servers.
+
+Just substitute `(projectname)` and `(packagedirectory)`
+with the appropriate information.
+
+.. code:: yaml
+
+    version: 2
+    build:
+    os: "ubuntu-22.04"
+    tools:
+        python: "3.10"
+    commands:
+        - pip install pydoctor
+        - | 
+        pydoctor \
+        --project-name=(projectname) \
+        --project-version=${READTHEDOCS_GIT_IDENTIFIER} \
+        --project-url=${READTHEDOCS_GIT_CLONE_URL%*.git} \
+        --html-viewsource-base=${READTHEDOCS_GIT_CLONE_URL%*.git}/tree/${READTHEDOCS_GIT_COMMIT_HASH} \
+        --html-base-url=${READTHEDOCS_CANONICAL_URL} \
+        --html-output $READTHEDOCS_OUTPUT/html/ \
+        --docformat=restructuredtext \
+        --intersphinx=https://docs.python.org/3/objects.inv \
+        ./(packagedirectory)
+
+`More on ReadTheDocs build customizations <https://docs.readthedocs.io/en/stable/build-customization.html>`_.

docs/source/quickstart.rst

@@ -26,7 +26,7 @@ The result looks like `this <api/index.html>`_.
 
     pydoctor \
         --project-name=pydoctor \
-        --project-version=1.2.0 \
+        --project-version=20.7.2 \
         --project-url=https://github.com/twisted/pydoctor/ \
         --html-viewsource-base=https://github.com/twisted/pydoctor/tree/20.7.2 \
         --html-base-url=https://pydoctor.readthedocs.io/en/latest/api \
@@ -54,6 +54,9 @@ Output files are static HTML pages which require no extra server-side support.
 Here is a `GitHub Action example <publish-github-action.html>`_ to automatically
 publish your API documentation to your default GitHub Pages website.
 
+Here is a `ReadTheDocs configuration <publish-readthedocs.html>`_ to automatically
+publish your API documentation to ReadTheDocs
+
 Return codes
 ------------