Merge pull request #37 from DiamondLightSource/switch-docs-to-sphinx

Switch docs to sphinx

Author: ptsOSL

.copier-answers.yml

@@ -9,7 +9,7 @@ component_type: library
 description: Accelerator Toolbox Interface for Pytac
 distribution_name: atip
 docker: false
-docs_type: README
+docs_type: sphinx
 git_platform: github.com
 github_org: DiamondLightSource
 package_name: atip

.github/workflows/_docs.yml

@@ -0,0 +1,54 @@
+on:
+  workflow_call:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Avoid git conflicts when tag and branch pushed at same time
+        if: github.ref_type == 'tag'
+        run: sleep 60
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # Need this to get version number from last tag
+          fetch-depth: 0
+
+      - name: Install system packages
+        run: sudo apt-get install graphviz
+
+      - name: Install python packages
+        uses: ./.github/actions/install_requirements
+
+      - name: Build docs
+        run: tox -e docs
+
+      - name: Remove environment.pickle
+        run: rm build/html/.doctrees/environment.pickle
+
+      - name: Upload built docs artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: build
+
+      - name: Sanitize ref name for docs version
+        run: echo "DOCS_VERSION=${GITHUB_REF_NAME//[^A-Za-z0-9._-]/_}" >> $GITHUB_ENV
+
+      - name: Move to versioned directory
+        run: mv build/html .github/pages/$DOCS_VERSION
+
+      - name: Write switcher.json
+        run: python .github/pages/make_switcher.py --add $DOCS_VERSION ${{ github.repository }} .github/pages/switcher.json
+
+      - name: Publish Docs to gh-pages
+        if: github.ref_type == 'tag' || github.ref_name == 'main'
+        # We pin to the SHA, not the tag, for security reasons.
+        # https://docs.github.com/en/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: .github/pages
+          keep_files: true

.github/workflows/ci.yml

@@ -34,6 +34,11 @@ jobs:
     secrets:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
+  docs:
+    needs: check
+    if: needs.check.outputs.branch-pr == ''
+    uses: ./.github/workflows/_docs.yml
+
   dist:
     needs: check
     if: needs.check.outputs.branch-pr == ''
@@ -48,7 +53,7 @@ jobs:
 
   release:
     if: github.ref_type == 'tag'
-    needs: [dist]
+    needs: [dist, docs]
     uses: ./.github/workflows/_release.yml
     permissions:
       contents: write

.github/workflows/periodic.yml

@@ -0,0 +1,13 @@
+name: Periodic
+
+on:
+  workflow_dispatch:
+  schedule:
+    # Run weekly to check URL links still resolve
+    - cron: "0 8 * * WED"
+
+jobs:
+  linkcheck:
+    uses: ./.github/workflows/_tox.yml
+    with:
+      tox: docs build -- -b linkcheck

INSTALL.rst

@@ -20,11 +20,10 @@ Initial Setup and Installation
     $ cd <source-directory>
     $ git clone https://github.com/DiamondLightSource/atip.git
 
-2. Create a pipenv and install the dependencies::
+2. From within a python virtual environment, install the dependencies::
 
     $ cd atip
-    $ pipenv install --dev
-    $ pipenv shell
+    $ pip install -e ./
 
 3. Run the tests to ensure everything is working correctly::
 

README.md

@@ -3,30 +3,35 @@
 [![PyPI](https://img.shields.io/pypi/v/atip.svg)](https://pypi.org/project/atip)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
 
-# atip
 
-Accelerator Toolbox Interface for Pytac
+# ATIP - Accelerator Toolbox Interface for Pytac
 
-This is where you should write a short paragraph that describes what your module does,
-how it does it, and why people should use it.
+ATIP is an addition to  [Pytac](<https://github.com/DiamondLightSource/pytac>),
+a framework for controlling particle accelerators. ATIP adds a simulator to
+Pytac, which can be used and addressed in the same way as a real accelerator.
 
-Source          | <https://github.com/DiamondLightSource/atip>
-:---:           | :---:
-PyPI            | `pip install atip`
-Releases        | <https://github.com/DiamondLightSource/atip/releases>
+ATIP enables the easy offline testing of high level accelerator
+controls applications, by either of two methods:
 
-This is where you should put some images or code snippets that illustrate
-some relevant examples. If it is a library then you might put some
-introductory code here:
+* By replacing the real accelerator at the point where it is addressed by the
+  software, in the Pytac lattice object;
 
-```python
-from atip import __version__
+* In a standalone application as a "virtual accelerator", publishing the same
+  control system interface as the live machine. At Diamond Light Source this
+  has been implemented with EPICS, and run on a different port to the
+  operational control system. So the only change required to test software is
+  to configure this EPICS port.
 
-print(f"Hello atip {__version__}")
-```
+The python implementation of
+[Accelerator Toolbox](<https://github.com/atcollab/at>) (pyAT) is used for the
+simulation.
 
-Or if it is a commandline tool then you might put some example commands here:
+Source          | <https://github.com/DiamondLightSource/atip>
+:---:           | :---:
+PyPI            | `pip install atip`
+Docker          | `docker run ghcr.io/diamondlightsource/atip:latest`
+Documentation   | <https://diamondlightsource.github.io/atip>
+Installation    | <https://diamondlightsource.github.io/atip/tutorials/installation>
+Releases        | <https://github.com/DiamondLightSource/atip/releases>
 
-```
-python -m atip --version
-```
+<!-- README only content. Anything below this line won't be included in index.md -->