Use readthedocs CI for building documentation (#3328)

* Remove docs.yml CI 

* Enable readthedocs build on pull requests

* Remove conda dependencies

* Update docs build instructions

.readthedocs.yml

@@ -1,9 +1,30 @@
 version: 2
 
+sphinx:
+  configuration: docs/conf.py
+
 build:
   os: "ubuntu-22.04"
   tools:
-    python: "mambaforge-22.9"
+    python: "3.12"
+  apt_packages:
+    - build-essential
+    - libx11-dev
+    - libxcomposite-dev
+    - libmpich-dev
+    - ffmpeg
+    - doxygen
+    - pandoc
+    - cmake
+    - bison
+    - flex
+    - libfl-dev
+    - libreadline-dev
+
+submodules:
+  recursive: true
 
-conda:
-  environment: docs/conda_environment.yml
+python:
+  install:
+    - requirements: nrn_requirements.txt
+    - requirements: docs/docs_requirements.txt

docs/README.md

@@ -1,17 +1,27 @@
 ## NEURON Documentation
 
 ### Online
+
 Latest NEURON documentation is available on:
-*  ReadTheDocs @ [https://nrn.readthedocs.io/en/latest/](https://nrn.readthedocs.io/en/latest/).
-* GithubPages @ [https://neuronsimulator.github.io/nrn/](https://neuronsimulator.github.io/nrn/).
+
+* ReadTheDocs @ [https://nrn.readthedocs.io/en/latest/](https://nrn.readthedocs.io/en/latest/).
 
 Contents:
+
 * Documentation on building NEURON
 * User documentation (HOC, Python, tutorials, rxd)
 * Developer documentation (SCM, technical topics, Doxygen)
 
+### On pull requests
+
+The documentation is built automatically as part of continuous integration (CI) when a pull request is opened, under the name `docs/readthedocs.org:nrn`.
+Upon success, it can viewed by clicking on the "Details" link to the right of the name.
+If the build fails, the logs will be available at the same link.
+
 ### Local build
 
+To build the NEURON documentation, one needs to install the same prerequisites as for building NEURON itself; see the [install instructions](./install/install_instructions.md) for a complete list of build dependencies.
+
 #### Virtual environment
 It is recommended to use a Python virtual environment, for example:
 
@@ -20,31 +30,18 @@ python3 -m venv venv
 source venv/bin/activate
 ```
 
-
 In order to build documentation locally, you need to pip install the ``docs_requirements.txt`` :
 ```
 pip3 install -r docs/docs_requirements.txt --upgrade
 ```
 
-Also, make sure to have `Doxygen` and `pandoc` installed, and the dependencies listed in [conda_environment.yml](conda_environment.yml)
-Note that this conda environment file is tailored to the online ReadTheDocs setup (but it lists out all desired requirements, so make sure to check it out).
-On Mac, you can install these packages using `brew`:
+Also, make sure to have `Doxygen` and `pandoc` installed.
+On MacOS, you can install these packages using `brew`:
 
 ```bash
 brew install doxygen pandoc
 ```
 
-#### Anaconda environment
-
-After installing Anaconda, create a new environment with the following command:
-
-```bash
-conda env create --quiet --name rtd --file docs/conda_environment.yml
-conda activate rtd
-```
-
-This will install all dependencies needed to build the documentation locally, in a similar way as on ReadTheDocs. However ReadTheDocs has a different setup, so it is of interest to head over and check the build logs for additional information.
-
 #### Confguring the build
 
 With all dependencies installed, configure project with CMake (>= v3.17) as described in [CMake Build Options](./cmake_doc/options.rst#nrn-enable-docs-bool-off).
@@ -86,30 +83,34 @@ When working locally on documentation, depending on what you work on, be aware o
 * `sphinx` target is the one that will assemble all generated output (doxygen, notebooks).
 
 ### ReadTheDocs setup
+
 #### Config file
+
 Configuration file is in the top directory: [../.readthedocs.yml](../.readthedocs.yml).
 
 #### Documentation not handled by RTD
+
 For RTD we need to call `doxygen` and `notebooks` make targets, since only `sphinx` executable is called therein.
-To that end we are using conda to be able to install packages like CMake in RTD.
-All conda dependencies are listed under [conda_environment.yml](conda_environment.yml).
 
 #### Leveraging `conf.py`
+
 The only way to gather extra documentation in RTD is to make use of `conf.py`.
 Have a look at `if os.environ.get("READTHEDOCS"):` block in [conf.py](conf.py) to see how we leverage the aforementioned targets and outputs.
 
 #### Notebooks execution with `neuron` wheels
+
 For `notebooks` we are using `neuron` Python wheel as follows:
 * `neuron-nightly` for `master` RTD builds.
 * `neuron==X.Y.Z` for `release` RTD builds. Note that wheels need to be published first (see next section).
 
-To achieve this, we parse the RTD environment variable `READTHEDOCS_VERSION` and `pip install` it (see [conf.py](conf.py)) .
+To achieve this, we parse the RTD environment variable `READTHEDOCS_VERSION` and `pip install` it (see [conf.py](conf.py)).
 
 #### New release on RTD
-Follow the following steps:
+
+To create a new public release on RTD, follow these steps:
+
 * create a new release (see [GHA Neuron Release - Manual Workflow](https://github.com/neuronsimulator/nrn/actions?query=workflow%3A%22NEURON+Release%22))
 * publish the wheels (these will be pip-installed by RTD)
-* go to [NRN RTD Versions page](https://readthedocs.org/projects/nrn/versions/) and activate the new tag.  
+* go to [NRN RTD Versions page](https://readthedocs.org/projects/nrn/versions/) and activate the new tag. Make sure that the version is not marked as hidden.
 
-**NOTE**: build can be re-launched as many times as needed
-
+**NOTE**: builds can be re-launched as many times as needed

docs/conf.py

@@ -10,6 +10,7 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
+import glob
 import os
 import sys
 import subprocess
@@ -115,17 +116,32 @@ def setup(app):
 
     rtd_ver = PKGVER.parse(os.environ.get("READTHEDOCS_VERSION"))
 
-    # Install neuron accordingly (nightly for master, otherwise incoming version)
-    # Note that neuron wheel must be published a priori.
-    subprocess.run(
-        "pip install neuron{}".format(
-            "=={}".format(rtd_ver.base_version)
-            if isinstance(rtd_ver, PKGVER.Version)
-            else "-nightly"
-        ),
-        shell=True,
-        check=True,
-    )
+    # see:
+    # https://docs.readthedocs.com/platform/stable/reference/environment-variables.html#envvar-READTHEDOCS_VERSION_TYPE
+    if os.environ.get("READTHEDOCS_VERSION_TYPE") == "external":
+        # Build and install NEURON from source
+        subprocess.run(
+            "cd .. && python setup.py build_ext bdist_wheel",
+            shell=True,
+            check=True,
+        )
+        subprocess.run(
+            f"pip install {glob.glob('../dist/*.whl')[0]}",
+            shell=True,
+            check=True,
+        )
+    else:
+        # Install neuron accordingly (nightly for master, otherwise incoming version)
+        # Note that neuron wheel must be published a priori.
+        subprocess.run(
+            "pip install neuron{}".format(
+                f"=={rtd_ver.base_version}"
+                if isinstance(rtd_ver, PKGVER.Version)
+                else "-nightly"
+            ),
+            shell=True,
+            check=True,
+        )
 
     # Execute & convert notebooks + doxygen
     subprocess.run("cd .. && python setup.py docs", check=True, shell=True)