Fix merge conflicts

.circleci/config.yml

@@ -1,17 +1,16 @@
 version: 2
 jobs:
-  build-odkx:
+  build:
     working_directory: ~/work
     docker:
-      - image: circleci/python:3.9
+      - image: cimg/python:3.11
     steps:
       - checkout
       - run:
-          name: Install checkout requirements
+          name: Install checkout requirements (large-file-support)
           command: |
             sudo apt-get update
             sudo apt-get install git-lfs
-            git lfs install
       - run:
           name: Checkout binaries
           command: git lfs pull
@@ -20,35 +19,35 @@ jobs:
           command: |
             sudo apt-get install pngquant
             sudo apt-get install python3-enchant
-            sudo pip install -r requirements.txt
+            pip3 install --user -r requirements.txt
+            pip3 install --user -r style-test-requirements.txt
       - run:
-          name: Style Guide Check
+          name: Generate html output
+          command: make dirhtml
+      - run:
+          name: Check spelling
           command: |
-            paths=$(git diff origin/master... --name-only)
-            echo $paths
-            sudo python style-test.py $paths -r odkx-src
-            sudo python style-test.py $paths -r shared-src
+            make spelling
+            python3 util/check-spelling-output.py build/spelling
       - run:
-          name: Build ODK-X Documentation
-          command: make odkx-deploy
+          name: Compress images
+          command: pngquant build/dirhtml/_images/*.png --force --ext .png --verbose
       - run:
-          name: Check spelling of ODK-X Documentation
-          command: make odkx-spell-check
+          name: Style check of changed files
+          command: |
+            paths=$(git diff origin/main --name-only)
+            python3 style-test.py $paths -r src
       - run:
           name: Build LaTex of ODK-X Documentation
-          command: make odkx-latex
-      - run:
-          name: Compress images
-          command: pngquant odkx-build/_images/*.png --force --ext .png --verbose
+          command: make latex
       - store_artifacts:
-          path: odkx-build
-          destination: odkx-build
+          path: build
       - persist_to_workspace:
           root: ~/work
           paths:
-            - odkx-build/*
+            - build/*
             - s3_website.yml
-  build-pdf-odkx:
+  build-pdf:
     working_directory: ~/work
     docker:
       - image: schickling/latex
@@ -58,20 +57,19 @@ jobs:
       - run:
           name: Build PDF
           command: |
-              cd odkx-build/latex
+              cd build/latex
               xelatex ODK-X.tex
               xelatex ODK-X.tex
-              mkdir -p ../_downloads
-              mv ODK-X.pdf ../_downloads/ODK-X-Documentation.pdf
+              mkdir -p ../dirhtml/_downloads
+              mv ODK-X.pdf ../dirhtml/_downloads/ODK-X-Documentation.pdf
       - store_artifacts:
-          path: odkx-build/_downloads/ODK-X-Documentation.pdf
+          path: build/dirhtml/_downloads/ODK-X-Documentation.pdf
           destination: ODK-X-Documentation.pdf
       - persist_to_workspace:
           root: ~/work
           paths:
-            - odkx-build/*
-
-  deploy-odkx:
+            - build/dirhtml/*
+  deploy:
     working_directory: ~/work
     docker:
       - image: cimg/ruby:3.2
@@ -81,9 +79,11 @@ jobs:
       - run:
           name: Install deploy requirements
           command: |
+              if [[ "$CIRCLE_PROJECT_USERNAME" == "odk-x" ]]; then \
                 sudo apt-get update
                 sudo apt-get install -y pngquant openjdk-11-jre-headless
                 gem install s3_website_revived && s3_website install
+              fi
       - run:
           name: Push to S3
           command: |
@@ -93,16 +93,16 @@ workflows:
   version: 2
   build_deploy:
     jobs:
-      - build-odkx
-      - build-pdf-odkx:
+      - build
+      - build-pdf:
           requires:
-            - build-odkx
-      - deploy-odkx:
+            - build
+      - deploy:
           context: AWS
           requires:
-            - build-odkx
-            - build-pdf-odkx
+            - build
+            - build-pdf
           filters:
             branches:
               only: 
-                - master
+                - main             

Dockerfile

@@ -1,4 +1,4 @@
-FROM python:3.9.16-buster
+FROM python:3.12.1
 
 WORKDIR /mnt
 
@@ -13,6 +13,6 @@ RUN apt-get update -y && \
 	python -m pip install --upgrade pip && \
     pip install --no-cache-dir -r requirements.txt
 
-ENTRYPOINT ["make"]
+ENTRYPOINT ["make", "dockerserve"]
 
 EXPOSE 8080

Makefile

@@ -1,65 +1,28 @@
 # Minimal makefile for Sphinx documentation
 #
 
-# You can set these variables from the command line.
-PYTHON = python3
-SPHINXOPTS    = 
-SPHINXBUILD   = sphinx-build
-ODKX_SRCDIR   = odkx-src
-COMPILE_X_SRCDIR = tmpx-src
-ODKX_BUILDDIR = odkx-build
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCE_DIR     = src
+BUILD_DIR      = build
 
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCE_DIR)" "$(BUILD_DIR)" $(SPHINXOPTS) $(O)
 
 .PHONY: help Makefile
 
-odkx-autobuild:
-	sphinx-autobuild --port 8080 --host 0.0.0.0 odkx-src odkx-build
+dockerserve:
+	sphinx-autobuild --host 0.0.0.0 --port 8080 -b dirhtml "$(SOURCE_DIR)" "$(BUILD_DIR)/html"
 
-odkx-clean:
-	rm -rf $(COMPILE_X_SRCDIR)
-	rm -rf $(ODKX_BUILDDIR)
+serve:
+	sphinx-autobuild -b dirhtml "$(SOURCE_DIR)" "$(BUILD_DIR)/html"
 
-odkx-clean-files:
-	rm -rf $(COMPILE_X_SRCDIR)
-	rm -rf $(ODKX_BUILDDIR)/*
+autobuild : serve
 
-clean: odkx-clean
-
-odkx-copy: odkx-clean-files
-	mkdir $(COMPILE_X_SRCDIR)
-	cp -rf $(ODKX_SRCDIR)/* $(COMPILE_X_SRCDIR)
-
-odkx: odkx-copy
-	@$(SPHINXBUILD) -b dirhtml "$(COMPILE_X_SRCDIR)" "$(ODKX_BUILDDIR)" $(SPHINXOPTS)
-
-odkx-deploy: odkx-copy
-	@$(SPHINXBUILD) -W -b dirhtml "$(COMPILE_X_SRCDIR)" "$(ODKX_BUILDDIR)" $(SPHINXOPTS)
-
-build-all: odkx
-
-odkx-build: odkx
-
-odkx-latex: odkx
-	@$(SPHINXBUILD) -b latex "$(COMPILE_X_SRCDIR)" "$(ODKX_BUILDDIR)"/latex $(SPHINXOPTS)
-	$(PYTHON) util/resize.py "$(ODKX_BUILDDIR)"
-
-odkx-pdf: odkx-latex
-	cd "$(ODKX_BUILDDIR)"/latex && \
-	xelatex ODK-X.tex && \
-	xelatex ODK-X.tex && \
-	mkdir -p ../_downloads && \
-	mv ODK-X.pdf ../_downloads/ODK-X-Documentation.pdf
-
-odkx-style-check: odkx
-	$(PYTHON) style-test.py -r $(COMPILE_X_SRCDIR)
-
-odkx-spell-check: odkx
-	sphinx-build -b spelling $(COMPILE_X_SRCDIR) $(ODKX_BUILDDIR)/spelling
-	$(PYTHON) util/check-spelling-output.py $(ODKX_BUILDDIR)
-
-odkx-check: odkx-style-check odkx-spell-check
-
-check-all: odkx-check
-
-test:
-	pytest
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCE_DIR)" "$(BUILD_DIR)" $(SPHINXOPTS) $(O)

README.md

@@ -1,6 +1,6 @@
 # ODK-X Docs
 
-![Platform](https://img.shields.io/badge/platform-Sphinx-blue.svg) [![License](https://img.shields.io/badge/license-CC%20BY%204.0-blue.svg)](https://creativecommons.org/licenses/by/4.0/) [![Build status](https://circleci.com/gh/odk-x/docs.svg?style=shield&circle-token=:circle-token)](https://circleci.com/gh/odk-x/docs/)  [![Netlify Status](https://api.netlify.com/api/v1/badges/d3788b3e-1abc-431d-a9a3-e5c71b20e053/deploy-status)](https://app.netlify.com/sites/blissful-bohr-7f32fb/deploys)
+![Platform](https://img.shields.io/badge/platform-Sphinx-blue.svg) [![License](https://img.shields.io/badge/license-CC%20BY%204.0-blue.svg)](https://creativecommons.org/licenses/by/4.0/) [![Build status](https://circleci.com/gh/odk-x/docs.svg?style=svg)](https://circleci.com/gh/odk-x/docs/)
 
 This repo is the source for ODK-X documentation.
 
@@ -53,19 +53,21 @@ Clone the docs repo into a directory you want the ODK-X docs files to be located
 1. Visit this link https://github.com/odk-x/docs on your browser to locate the docs repo
 2. Find and click the "fork" button to create a personal fork of the project on Github
 3. Navigate to the directory you want the files to be located using the "cd" (Change Directory) command on a command-line interface on your local machine:
+
 ```
 cd <DIRECTORY>
 ```
-4. Get a copy of the ODK-X docs repository on your local machine by cloning the forked repo to your local machine from your github account using the clone command below. Replace "LINK-TO-YOUR-FORKED-REPO" below with the actual link to your forked repo:  
-
+
+4. Get a copy of the ODK-X docs repository on your local machine by cloning the forked repo to your local machine from your github account using the clone command below. Replace "LINK-TO-YOUR-FORKED-REPO" below with the actual link to your forked repo: You need to click on the green "Code" button to get the "LINK-TO-YOUR-FORKED-REPO"
+
 ```
 git clone <LINK-TO-YOUR-FORKED-REPO>
 ```
 
-
 It can take a long time (>10 minutes) to clone the repo due to the large number of images in the docs. If you get an error such as `Smudge error` or `GitHub's rate limit reached`, run `git checkout -f HEAD` until you get the message `Checking out files: 100% done`.
 
 After the git clone finishes, use the below command to change the directory to the ODK-X docs directory
+
 ```
 cd docs
 ```
@@ -91,14 +93,25 @@ Take note of the full-stop `.` at the end of the build command. The `.` specifie
 ### Building and serving the docs locally
 
 Build and serve the docs locally with:
- * Windows: `.\run-task.bat odkx-autobuild`
- * Linux/macOS: `./run-task.sh odkx-autobuild`
+ * Windows: `.\run-task.ps1`
+ * Linux/macOS: `./run-task.sh`
 
 Once your terminal shows a "Serving on http://0.0.0.0:8080" message, you can then view the docs in your browser at http://localhost:8080.
 
-Changes you make in the source files will automatically be built and shown in your browser.
+Changes you make in the source files (located in the `./src` folder) will automatically be re-built and shown in your browser.
+
+* Windows: The docker container with the docs website will occupy the terminal window and output log messages when changes are detected and rebuilds are made. Open a new terminal window/tab to be able to stop the container using the command below.
+* Linux/macOs: Open a new terminal to interact with the container or press `Ctrl-Z` on your keyboard to suspend the job. The job will still be running in the background and changes will automatically be rebuilt and served.
+
+
+To stop the container, type the following command
+
+```
+docker stop odkx-docs
+```
+
+
 
-Press `Ctrl-C` on your keyboard to stop the build server. It could take a while to effectively stop, and you can always close the terminal window.
 
 If you get a `The name "odkx-docs" is already in use by container` error message, run the following command:
 
@@ -219,21 +232,25 @@ It can take a long time (>10 minutes) to clone the repo due to the large number
 
 Once your environment is set up, build and serve the docs locally with:
 
+```bash
+$ make serve
+```
+
 ```bash
 $ make odkx
-$ cd odkx-build
+$ cd build
 $ python -m http.server 8000
 ```
 
-You can then view the docs in your browser at [http://localhost:8000/odkx-build/](http://localhost:8000/odkx-build/).
+You can then view the docs in your browser at [http://localhost:8000/build/](http://localhost:8000/build/).
 
 You can also use `make` to run just a portion of the build process. See available [build tasks](#tasks) below.
 
 ## <a name="tasks"></a>Build tasks
 
-|             | Build & Serve  |   Build    |   Copy    |   LaTeX    |   Style Check    |   Spell Check    | Check All  |
-| ----------- | :------------: | :--------: | :-------: | :--------: | :--------------: | :--------------: | :--------: |
-| **Options** | odkx-autobuild | odkx-build | odkx-copy | odkx-latex | odkx-style-check | odkx-spell-check | odkx-check |
+|             | Build & Serve  |   Build    |   Copy    |   LaTeX    |   PDF      |   Style Check    | Spell Check      | Check All  |
+| ----------- | :------------: | :--------: | :-------: | :--------: | :--------: | :--------------: | :--------------: | :--------: |
+| **Options** | serve          | build      | copy      | latex      | pdf        | style-check      | spell-check      | check-all  |
 
 
 ## How to contribute?

make.bat

@@ -6,9 +6,9 @@ if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=python -msphinx
 )
 
-set ODKX_SRCDIR=odkx-src
-set COMPILE_X_SRCDIR=tmpx-src
-set ODKX_BUILDDIR=odkx-build
+set ODKX_SRCDIR=src
+set COMPILE_X_SRCDIR=tmp_src
+set ODKX_BUILDDIR=build
 
 if "%1" == "clean" goto cleancmd
 if "%1" == "copy" goto copy