GitHub pages action

.github/workflows/docs.yml

@@ -0,0 +1,87 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    types: [opened, reopened, synchronize, closed]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  # Publish main docs to atomica.tools/docs/main/
+  publish:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    concurrency:
+      group: docs-${{ github.ref_name }}
+      cancel-in-progress: true
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+      - name: Install pandoc
+        run: sudo apt-get install -y pandoc
+      - name: Install Python dependencies
+        run: |
+          python -m pip install uv
+          uv pip install --system -e ".[docs]"
+      - name: Build documentation
+        run: python -m sphinx.cmd.build docs doc_build -j2
+      - name: Deploy to atomicateam/docs
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          repository-name: atomicateam/docs
+          token: ${{ secrets.DOCS_DEPLOY_TOKEN }}
+          branch: master               # docs repo serves Pages from master root
+          folder: doc_build
+          target-folder: ${{ github.ref_name }}
+          clean: true                  # scoped to target-folder; leaves other folders, .nojekyll and index.html intact
+          single-commit: true          # keep the docs repo history from ballooning
+
+  # Deploy/remove a per-PR preview at atomica.tools/docs/pr-preview/pr-<N>/
+  preview:
+    # Skip forks: they cannot access the deploy secret
+    if: >-
+      github.event_name == 'pull_request' &&
+      github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    concurrency:
+      group: docs-preview-${{ github.event.number }}
+      cancel-in-progress: true
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        if: github.event.action != 'closed'
+        with:
+          python-version: '3.14'
+      - name: Install pandoc
+        if: github.event.action != 'closed'
+        run: sudo apt-get install -y pandoc
+      - name: Install Python dependencies
+        if: github.event.action != 'closed'
+        run: |
+          python -m pip install uv
+          uv pip install --system -e ".[docs]"
+      - name: Build documentation
+        if: github.event.action != 'closed'
+        run: python -m sphinx.cmd.build docs doc_build -j2
+      - name: Deploy / update / remove preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          token: ${{ secrets.DOCS_DEPLOY_TOKEN }}
+          source-dir: doc_build
+          deploy-repository: atomicateam/docs
+          preview-branch: master
+          umbrella-dir: pr-preview
+          pages-base-url: atomica.tools/docs
+          qr-code: false
+          wait-for-pages-deployment: true
+          action: auto

azure-pipelines.yml

@@ -45,40 +45,7 @@ jobs:
         summaryFileLocation: '$(System.DefaultWorkingDirectory)/**/coverage.xml'
 #        reportDirectory: '$(System.DefaultWorkingDirectory)/**/htmlcov'
 
-- job: 'docs'
-  condition: and(ne(variables['Build.Reason'], 'PullRequest'), ne(variables['Build.Reason'], 'Schedule')) # Skip if it's a PR build or a scheduled build
-  pool:
-    vmImage: 'ubuntu-latest'
-  steps:
-    - task: UsePythonVersion@0
-      displayName: 'Select python version'
-      inputs:
-        versionSpec: '3.14'
-    - script: |
-        sudo apt install pandoc -y
-      displayName: 'Install pandoc'
-    - script: |
-        python -m pip install uv
-        uv pip install --system -e ".[docs]"
-      displayName: 'Install Python dependencies'
-    - script: |
-        mkdir doc_build
-        python -m sphinx.cmd.build "docs" "doc_build/$(Build.SourceBranchName)" -j2
-      displayName: 'Build documentation'
-      # Invoke directly with `python -m sphinx.cmd.build` instead of `sphinx-build` to avoid "sphinx-build: command not found" on Azure
-    - script: |
-        git clone --depth 1 https://github.com/atomicateam/docs doc_repo
-        rm -rf doc_repo/$(Build.SourceBranchName)
-        mv doc_build/$(Build.SourceBranchName) doc_repo/$(Build.SourceBranchName)
-        git -C doc_repo config user.email ci@azurepipelines
-        git -C doc_repo config user.name "Azure Pipelines"
-        git -C doc_repo add .
-        git -C doc_repo commit -m "Automatic update"
-        git -C doc_repo push https://$(GithubToken)@github.com/atomicateam/docs
-      displayName: 'Publish site'
-#    - publish: docs/_build
-#      artifact: docs
-#      displayName: 'Publish documentation as Azure zip file'
+# Documentation is built and published via GitHub Actions (.github/workflows/docs.yml)
 
 - job: 'deploy'
   dependsOn: 'tox'

docs/examples/Basic-workflow.ipynb

@@ -148,7 +148,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "For full details on plotting, please refer to the full plotting documentation [here](https://atomica.tools/docs/master/examples/Plotting.html)."
+    "For full details on plotting, please refer to the full plotting documentation [here](https://atomica.tools/docs/main/examples/Plotting.html)."
    ]
   },
   {
@@ -501,7 +501,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "For more details on the optimization system, see the [general documentation](https://atomica.tools/docs/master/general/Optimization.html) on optimization."
+    "For more details on the optimization system, see the [general documentation](https://atomica.tools/docs/main/general/Optimization.html) on optimization."
    ]
   }
  ],

docs/general/Optimization.md

@@ -62,7 +62,7 @@ An `Adjustment` contains
 An `Adjustment` has the following methods
 
 - `Adjustment.get_initialization(progset,instructions)` - this method returns a vector of initial values for each adjustable, which are the default initial values for ASD. There are several possible places where initial values can be stored. Consider spending values. In order of precedence, the places where default values could be defined are:
-	- In the `Adjustable`. For example, the `SpendingAdjustment` in an optimization might wish to explictly store an initial value to start the optimization at
+	- In the `Adjustable`. For example, the `SpendingAdjustment` in an optimization might wish to explicitly store an initial value to start the optimization at
 	- In the `ProgramInstructions` - the program instructions optionally contains a `TimeSeries` of spending values that overwrite the data spending values stored in the `ProgramSet`, which is the used to implementing budget scenarios
 	- In the `ProgramSet`, each program by default has spending specified in the Progbook file
 

docs/general/population-types/Population-Types.rst

@@ -40,7 +40,7 @@ The restriction that transfers cannot take place across population types helps t
 
 - There can never be a transfer between a mosquito population and a human population, because this would represent mosquitos turning into humans. Thus, a population type would be appropriate for this
 - Similarly, there can never be a transfer between a human population and the environment e.g. a human turning into a lake. Thus, an environment population to track water pollution would be well represented with a different population type
-- There may be a separate set of disease states if a model includes coinfection. For example, there may be more possible treatment states for TB+HIV compared to TB or HIV alone. If it is possible for an individual to move from TB to TB+HIV or between other coinfection states, then these should *not* be different population types. Instead, the all of the coinfection states should be added as compartments within a single population type
+- There may be a separate set of disease states if a model includes coinfection. For example, there may be more possible treatment states for TB+HIV compared to TB or HIV alone. If it is possible for an individual to move from TB to TB+HIV or between other coinfection states, then these should *not* be different population types. Instead, all of the coinfection states should be added as compartments within a single population type
 - Some nutrition models for maternal and child health model adult women and children completely independently, such that no children grow up and become adult women. In these types of models, children simply exit the model once they reach a certain age (e.g. 5 years old). For this type of model, it would be suitable to have separate population types for women and children. That way, stunting and wasting compartments would not need to be created for adults, only children. However, if it is possible for children to become adults within the model, then there should *not* be different population types - otherwise, it would be impossible to transfer people from the child populations to the adult population
 
 .. note::
@@ -77,7 +77,7 @@ Next, do the same for Characteristics and Parameters.
 
 Notice how the characteristics sheet has omitted the population type for the 'sir'-related quantities, which will be automatically assigned because the 'sir' population type is the first one in the list. In general, it is better to explicitly specify the population type for all quantities. However, if there are many quantities and only a few of them belong to a different population type, this default behaviour can make it easier to fill out the Framework.
 
-Note that characteristics cannot span population types - the included compartments and the denominator must all belong to the same population type as the characteristic itself. This is because characteristics are always evaluated within a single population, so all of the constitutents of the characteristic must exist within that population. 
+Note that characteristics cannot span population types - the included compartments and the denominator must all belong to the same population type as the characteristic itself. This is because characteristics are always evaluated within a single population, so all of the constituents of the characteristic must exist within that population. 
 
 .. image:: framework_4.png
 	:width: 650px
@@ -108,12 +108,12 @@ If your parameter function refers to an interaction, then the quantity being agg
 
 	If you want to have an interaction only between certain populations within a population type - for example, if only adults contribute to water pollution - then create an Interaction and set the weights to 0 in the databook for the populations that should be excluded.
 
-The final place population types appear in the Framework is in the transition matrix. Transitions are possible between compartments of the same population type. As a general rule, you should have as many transition matrices as you do population types with compartments. In the example above, there are three population types, but only the ``sir`` and ``udt`` population types have compartments within them. Therefore, we will have two transition matrices. These both appear on the 'Transitions' sheet. To define multiple transition matricies, simply insert them onto the transitions sheet stacked vertically, separated by an empty row. For example:
+The final place population types appear in the Framework is in the transition matrix. Transitions are possible between compartments of the same population type. As a general rule, you should have as many transition matrices as you do population types with compartments. In the example above, there are three population types, but only the ``sir`` and ``udt`` population types have compartments within them. Therefore, we will have two transition matrices. These both appear on the 'Transitions' sheet. To define multiple transition matrices, simply insert them onto the transitions sheet stacked vertically, separated by an empty row. For example:
 
 .. image:: framework_6.png
 	:width: 500px
 
-In the top left cell of the transition matrix, enter the code name for the population type. For example, the above screenshot shows 'udt' entered into cell A7. If the population type is omitted, it will default to the first population type in the framework. So the empty cell A1 will be automatically populated with 'sir' in this example. All of the compartments in the transition matrix must have the same type as the transition matrix itself (e.g., with 'udt' in cell A7, the compartment in cell B7 must exist in the 'udt' population type). This is atuomatically checked and validated when the framework is loaded. Similarly, all of the parameters in each transition matrix must belong the corresponding population type. 
+In the top left cell of the transition matrix, enter the code name for the population type. For example, the above screenshot shows 'udt' entered into cell A7. If the population type is omitted, it will default to the first population type in the framework. So the empty cell A1 will be automatically populated with 'sir' in this example. All of the compartments in the transition matrix must have the same type as the transition matrix itself (e.g., with 'udt' in cell A7, the compartment in cell B7 must exist in the 'udt' population type). This is automatically checked and validated when the framework is loaded. Similarly, all of the parameters in each transition matrix must belong the corresponding population type. 
 
 Databook population types
 --------------------------
@@ -137,7 +137,7 @@ Notice how every population has both a label and a type. The 'Population Definit
 
 .. warning::
 
-	The data entry rows are created when the databook is generated, and they take into account the population types. It is not possible to change the type of a population after it has been created. The population type cells are grey to reflect this. Changing the population type by overwriting those cells will likely result in an error (unless all of the data entry tables are also updated manually). Instead, you should load the databook into Atomica and programatically remove the old population, and make a new one with the desired type.  
+	The data entry rows are created when the databook is generated, and they take into account the population types. It is not possible to change the type of a population after it has been created. The population type cells are grey to reflect this. Changing the population type by overwriting those cells will likely result in an error (unless all of the data entry tables are also updated manually). Instead, you should load the databook into Atomica and programmatically remove the old population, and make a new one with the desired type.  
 
 The data entry tables are essentially unchanged from normal databooks where there is only one population type. However, notice that the available populations under each quantity depend on the population type. For example, 'All people with condition' is defined in the 'udt' population type, so data entry is provided only for the UDT populations.
 
@@ -174,7 +174,7 @@ Programs and population types
 
 Programs also support population types, but the implementation is relatively simple compared to frameworks and databooks. 
 
-On the 'Program targeting' sheet, all populations and all compartments are shown, regardless of which population type they are in. You can select any population and any compartment to target. The number of people targeted by the program is defined as the sum of all compartments that are targeted by the program. Thus, any nonexistent compartments will simply be skipped in the this summation. Consider the example shown below:
+On the 'Program targeting' sheet, all populations and all compartments are shown, regardless of which population type they are in. You can select any population and any compartment to target. The number of people targeted by the program is defined as the sum of all compartments that are targeted by the program. Thus, any nonexistent compartments will simply be skipped in this summation. Consider the example shown below:
 
 .. image:: progbook_1.png
 	:width: 650px

docs/general/programs/Programs.rst

@@ -70,7 +70,7 @@ When the program book is loaded in, these data are stored in three key classes
 
 - A :class:`ProgramSet` contains a collection of :class:`Program` objects and a collection of :class:`Covout` objects
 - A :class:`Program` object contains all of the information on the 'Program targeting' sheet and the 'Spending data' sheet. There is one program object for each row in the 'Program targeting' sheet
-- A :class:`Covout` object contains all of the information on a single row of the 'Program effects' sheet. It thus contains all of the program outcomes for a single parameter in a single population. Storing the program outcomes grouped by parameter rather than grouped by program facilitates computing interations between programs. This process is described in more detail below - :ref:`Outcomes`. 
+- A :class:`Covout` object contains all of the information on a single row of the 'Program effects' sheet. It thus contains all of the program outcomes for a single parameter in a single population. Storing the program outcomes grouped by parameter rather than grouped by program facilitates computing interactions between programs. This process is described in more detail below - :ref:`Outcomes`. 
 
 This class structure is depicted visually below: