Merge pull request #5 from ISISComputingGroup/docs

Docs

Author: Tom-Willemsen

.gitattributes

@@ -0,0 +1,4 @@
+* text=auto
+*.md text
+*.rst text
+*.rest text

.github/workflows/documentation.yml

@@ -0,0 +1,25 @@
+name: sphinx
+
+on: [push, workflow_call]
+
+jobs:
+  spellcheck:
+    runs-on: "windows-latest"
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: install requirements
+        run: pip install -e .[dev]
+      - name: run pytest
+        run: python -m pytest
+      - name: run spellcheck
+        run: sphinx-build -E -a -W --keep-going -b spelling doc _build
+  build:
+    uses: ISISComputingGroup/reusable-workflows/.github/workflows/sphinx.yml@main
+    secrets: inherit
+    with:
+      deploy-branch: "master"

.gitignore

@@ -0,0 +1,164 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+.idea/
+.vscode/
+
+.idea/*
+.venv/
+ibex_developers_manual.egg-info/
+build/
+_build/

README.md

@@ -1,3 +1,3 @@
 # The IBEX Developer's Manual
 
-[Click here to go to the GitHub wiki with the developer's manual.](https://github.com/ISISComputingGroup/ibex_developers_manual/wiki)
+[Click here to go to the GitHub wiki with the developer's manual.](https://isiscomputinggroup.github.io/ibex_developers_manual/)

doc/Client.md

@@ -0,0 +1,17 @@
+# IBEX GUI (Eclipse)
+
+## Getting Started
+
+```{toctree}
+:glob:
+:titlesonly:
+
+client/GUI-Getting-Started
+client/GUI-Coding
+client/GUI-Testing
+client/GUI-Eclipse
+client/GUI-CSS
+client/GUI-Other
+client/GUI-Troubleshooting
+client/GUI-Design
+```

doc/Deployment.md

@@ -0,0 +1,12 @@
+# Releases & Deployment
+
+```{toctree}
+:glob:
+:titlesonly:
+
+deployment/Creating-a-release
+deployment/Manual-System-Tests
+deployment/Deploy
+deployment/Patch
+deployment/Future
+```

doc/Editing-the-Wiki.md

@@ -0,0 +1,148 @@
+# Editing this Documentation
+
+This documentation is built using [sphinx](https://www.sphinx-doc.org/en/master/) and the [myst](https://myst-parser.readthedocs.io/en/latest/) markdown
+plugin. Both of these tools have excellent online documentation.
+
+Sphinx is a widely-adopted structured documentation tool, which scales well even for very large projects - for example it 
+is used to build [Python's documentation](https://docs.python.org/3/), the [Linux kernel documentation](https://docs.kernel.org/), and 
+the [EPICS documentation](https://docs.epics-controls.org/en/latest/).
+
+## Markdown
+
+Markdown is the preferred format, although any format supported by sphinx can be used if needed for example ReST or MediaWiki may be useful if moving documentation from other sources.
+
+For a 3-minute introduction to Markdown see ['Mastering Markdown'](https://guides.github.com/features/mastering-markdown/).
+
+## Page Titles
+
+A top-level heading (e.g. `#` markdown header) is used as the page title. **A page should only have one title** (at the top) - otherwise multiple links to that
+page will appear in the navigation structure. Subsections within a page should use sub-headers like `##` or `###`.
+
+The page title is independent from the filename of the markdown file - however, for clarity, choose to use similar titles and
+filenames wherever possible.
+
+## Adding & editing pages
+
+For simple edits to existing pages, editing can be done via the github interface. There is an "edit on github" button at
+the top of every page, which will take you to the relevant page in github to edit it.
+
+For more complex changes, for example adding new pages, it is recommended to make the changes and test them locally, to make sure
+that the navigation structure renders properly.
+
+When adding new pages, carefully consider at what level in the hierarchy the new page should be inserted. In particular, be cautious
+about adding pages at the very top level of the documentation - these can very quickly clutter the navigation.
+
+Some sphinx `toctrees` (Table-of-contents trees) are listed explicitly, to promote a natural reading order. Where this is the case,
+new pages will need to be added to the `toctree` in the document one level up from where the new page has been added - preserving a 
+natural reading order. Sphinx will warn you (and fail the build) if you forget to do this.
+
+## Building the wiki locally
+
+Check out the wiki into `c:\instrument\dev\ibex_developers_manual`:
+
+```shell
+cd c:\instrument\dev
+git clone https://github.com/ISISComputingGroup/ibex_developers_manual.git
+```
+
+Make a python virtual environment containing the wiki's dependencies:
+
+```
+cd c:\instrument\dev\ibex_developers_manual
+c:\instrument\apps\python3\python.exe -m venv .venv
+.venv\Scripts\activate
+python -m pip install -e .
+```
+
+Build the wiki (rebuilding automatically on changes):
+
+```
+sphinx-autobuild doc _build
+```
+
+The local wiki will then be available at [http://localhost:8000](http://localhost:8000) in your browser.
+
+If sphinx gets out of sync with changes, you can clear the cached build output and start again by running:
+
+```
+rmdir /s /q _build && sphinx-autobuild doc _build
+```
+
+
+## Adding DrawIO Diagram
+
+Create new diagram
+
+1. Visit [DrawIO](https://www.draw.io/) choose `device`
+1. Create New Diagram, select type etc.
+1. Edit diagram until you are happy
+1. choose `File` -> `Export` -> `Png...`
+1. Then make sure `Include a copy of my diagram` is ticked
+1. Add it to the folder in git, next to the page which will use it
+
+In wiki add to markdown using:
+
+    ![alternative text](<image name>.png)
+
+To edit this just open that png in `draw.io`.
+
+## Images
+
+To add images you need to check out the Wiki and add them manually. The images should go into a folder next to the page which will use them.
+
+```shell
+git add some/folder/test.png
+git commit -m "Added an image to Using the Wiki page"
+git push
+```
+
+You can then add the image in markdown using the URL `test.png`:
+
+    ![alternative text](test.png)
+
+## Spellchecking
+
+The wiki has a built-in spellchecker, which will automatically run when a commit
+is pushed to github.
+
+To run the spellchecker locally, use:
+
+```
+sphinx-build -b spelling doc _build
+```
+
+There is an additional dictionary of allowed words in `doc/spelling_wordlist.txt`. This
+is used for words which we know are spelt correctly, but are not in the default dictionary.
+
+The word list can be kept in order by running `sort_word_list` (which will be available in
+the python virtual environment). This is also enforced by CI, and can be checked locally by
+running `pytest`. Both of these tools should be run from the top-level of an `ibex_developers_manual`
+git checkout - the directory that contains `pyproject.toml`.
+
+Sphinx is strict about capitalisation; where multiple spellings are valid, the word will
+need to be added to the word list with each of the valid spellings. An exception is all-lowercase entries in the 
+word list - these also allow a variant with an initial capital letter. 
+
+Where a word or product has a preferred stylisation, for example **ActiveMQ** or **LabVIEW**, only that spelling 
+should be added to the word list. Proper nouns should not have uncapitalised variants added to the word list.
+
+## Admonitions
+
+Sphinx supports various admonitions, which can be used to draw the reader's attention to
+certain topics.
+
+For example:
+
+```
+:::{tip}
+This is a tip!
+:::
+```
+
+Will render as:
+
+:::{tip}
+This is a tip!
+:::
+
+The list of supported admonitions is [on the MyST documentation](https://myst-parser.readthedocs.io/en/latest/syntax/admonitions.html).