restructure wiki

Author: Tom-Willemsen

doc/uncategorised/README.md renamed to 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

@@ -1,71 +1,12 @@
 # Releases & Deployment
 
-## Releases
-
 ```{toctree}
 :glob:
 :titlesonly:
 
 deployment/Creating-a-release
-deployment/Manual-system-tests
-```
-
-## Deployment
-
-### IBEX
-
-```{toctree}
-:glob:
-:titlesonly:
-
-deployment/Updating-Instrument-Machines
-deployment/Deployment-on-an-Instrument-Control-PC
-deployment/IBEX-Deployment-on-Training-machine
-deployment/Autostart-IBEX-on-Computer-Restart
-deployment/Making-an-Instrument-Available-from-the-GUI
-deployment/Reviewing-Deploy-Tickets
-deployment/Deploy-script-workflow
-```
-
-### Supporting software
-
-```{toctree}
-:glob:
-:titlesonly:
-
-deployment/Installing-and-Upgrading-MySQL
-deployment/NPort-install
-deployment/Upgrade-Java
-deployment/Upgrade-ISISICP
-```
-
-## Patching
-
-```{toctree}
-:glob:
-:titlesonly:
-
-deployment/Modifying-Code-on-an-instrument
-deployment/Modifying-Device-on-an-Instrument
-deployment/Release-Single-IOC
-deployment/Modifying-Plugins-on-a-Deployed-Client
-```
-
-## VHD Build & Deployments
-
-```{toctree}
-:glob:
-:titlesonly:
-
-deployment/Mount-or-create-IBEX-VHDs
-```
-
-## Containers
-
-```{toctree}
-:glob:
-:titlesonly:
-
-deployment/Containerising-an-IOC
-deployment/Containerising-the-Archiver-Appliance
+deployment/Manual-System-Tests
+deployment/Deploy
+deployment/Patch
+deployment/Future
 ```

doc/Editing-the-Wiki.md

@@ -0,0 +1,101 @@
+# 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 [numpy documentation](https://numpy.org/doc/stable/).
+
+### 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`.
+
+### Adding 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)