|
| 1 | +# Editing this Documentation |
| 2 | + |
| 3 | +This documentation is built using [sphinx](https://www.sphinx-doc.org/en/master/) and the [myst](https://myst-parser.readthedocs.io/en/latest/) markdown |
| 4 | +plugin. Both of these tools have excellent online documentation. |
| 5 | + |
| 6 | +Sphinx is a widely-adopted structured documentation tool, which scales well even for very large projects - for example it |
| 7 | +is used to build [Python's documentation](https://docs.python.org/3/), the [Linux kernel documentation](https://docs.kernel.org/), and |
| 8 | +the [EPICS documentation](https://docs.epics-controls.org/en/latest/). |
| 9 | + |
| 10 | +## Markdown |
| 11 | + |
| 12 | +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. |
| 13 | + |
| 14 | +For a 3-minute introduction to Markdown see ['Mastering Markdown'](https://guides.github.com/features/mastering-markdown/). |
| 15 | + |
| 16 | +## Page Titles |
| 17 | + |
| 18 | +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 |
| 19 | +page will appear in the navigation structure. Subsections within a page should use sub-headers like `##` or `###`. |
| 20 | + |
| 21 | +The page title is independent from the filename of the markdown file - however, for clarity, choose to use similar titles and |
| 22 | +filenames wherever possible. |
| 23 | + |
| 24 | +## Adding & editing pages |
| 25 | + |
| 26 | +For simple edits to existing pages, editing can be done via the github interface. There is an "edit on github" button at |
| 27 | +the top of every page, which will take you to the relevant page in github to edit it. |
| 28 | + |
| 29 | +For more complex changes, for example adding new pages, it is recommended to make the changes and test them locally, to make sure |
| 30 | +that the navigation structure renders properly. |
| 31 | + |
| 32 | +When adding new pages, carefully consider at what level in the hierarchy the new page should be inserted. In particular, be cautious |
| 33 | +about adding pages at the very top level of the documentation - these can very quickly clutter the navigation. |
| 34 | + |
| 35 | +Some sphinx `toctrees` (Table-of-contents trees) are listed explicitly, to promote a natural reading order. Where this is the case, |
| 36 | +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 |
| 37 | +natural reading order. Sphinx will warn you (and fail the build) if you forget to do this. |
| 38 | + |
| 39 | +## Building the wiki locally |
| 40 | + |
| 41 | +Check out the wiki into `c:\instrument\dev\ibex_developers_manual`: |
| 42 | + |
| 43 | +```shell |
| 44 | +cd c:\instrument\dev |
| 45 | +git clone https://github.com/ISISComputingGroup/ibex_developers_manual.git |
| 46 | +``` |
| 47 | + |
| 48 | +Make a python virtual environment containing the wiki's dependencies: |
| 49 | + |
| 50 | +``` |
| 51 | +cd c:\instrument\dev\ibex_developers_manual |
| 52 | +c:\instrument\apps\python3\python.exe -m venv .venv |
| 53 | +.venv\Scripts\activate |
| 54 | +python -m pip install -e . |
| 55 | +``` |
| 56 | + |
| 57 | +Build the wiki (rebuilding automatically on changes): |
| 58 | + |
| 59 | +``` |
| 60 | +sphinx-autobuild doc _build |
| 61 | +``` |
| 62 | + |
| 63 | +The local wiki will then be available at [http://localhost:8000](http://localhost:8000) in your browser. |
| 64 | + |
| 65 | +If sphinx gets out of sync with changes, you can clear the cached build output and start again by running: |
| 66 | + |
| 67 | +``` |
| 68 | +rmdir /s /q _build && sphinx-autobuild doc _build |
| 69 | +``` |
| 70 | + |
| 71 | + |
| 72 | +## Adding DrawIO Diagram |
| 73 | + |
| 74 | +Create new diagram |
| 75 | + |
| 76 | +1. Visit [DrawIO](https://www.draw.io/) choose `device` |
| 77 | +1. Create New Diagram, select type etc. |
| 78 | +1. Edit diagram until you are happy |
| 79 | +1. choose `File` -> `Export` -> `Png...` |
| 80 | +1. Then make sure `Include a copy of my diagram` is ticked |
| 81 | +1. Add it to the folder in git, next to the page which will use it |
| 82 | + |
| 83 | +In wiki add to markdown using: |
| 84 | + |
| 85 | +  |
| 86 | + |
| 87 | +To edit this just open that png in `draw.io`. |
| 88 | + |
| 89 | +## Images |
| 90 | + |
| 91 | +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. |
| 92 | + |
| 93 | +```shell |
| 94 | +git add some/folder/test.png |
| 95 | +git commit -m "Added an image to Using the Wiki page" |
| 96 | +git push |
| 97 | +``` |
| 98 | + |
| 99 | +You can then add the image in markdown using the URL `test.png`: |
| 100 | + |
| 101 | +  |
| 102 | + |
| 103 | +## Spellchecking |
| 104 | + |
| 105 | +The wiki has a built-in spellchecker, which will automatically run when a commit |
| 106 | +is pushed to github. |
| 107 | + |
| 108 | +To run the spellchecker locally, use: |
| 109 | + |
| 110 | +``` |
| 111 | +sphinx-build -b spelling doc _build |
| 112 | +``` |
| 113 | + |
| 114 | +There is an additional dictionary of allowed words in `doc/spelling_wordlist.txt`. This |
| 115 | +is used for words which we know are spelt correctly, but are not in the default dictionary. |
| 116 | + |
| 117 | +The word list can be kept in order by running `sort_word_list` (which will be available in |
| 118 | +the python virtual environment). This is also enforced by CI, and can be checked locally by |
| 119 | +running `pytest`. Both of these tools should be run from the top-level of an `ibex_developers_manual` |
| 120 | +git checkout - the directory that contains `pyproject.toml`. |
| 121 | + |
| 122 | +Sphinx is strict about capitalisation; where multiple spellings are valid, the word will |
| 123 | +need to be added to the word list with each of the valid spellings. An exception is all-lowercase entries in the |
| 124 | +word list - these also allow a variant with an initial capital letter. |
| 125 | + |
| 126 | +Where a word or product has a preferred stylisation, for example **ActiveMQ** or **LabVIEW**, only that spelling |
| 127 | +should be added to the word list. Proper nouns should not have uncapitalised variants added to the word list. |
| 128 | + |
| 129 | +## Admonitions |
| 130 | + |
| 131 | +Sphinx supports various admonitions, which can be used to draw the reader's attention to |
| 132 | +certain topics. |
| 133 | + |
| 134 | +For example: |
| 135 | + |
| 136 | +``` |
| 137 | +:::{tip} |
| 138 | +This is a tip! |
| 139 | +::: |
| 140 | +``` |
| 141 | + |
| 142 | +Will render as: |
| 143 | + |
| 144 | +:::{tip} |
| 145 | +This is a tip! |
| 146 | +::: |
| 147 | + |
| 148 | +The list of supported admonitions is [on the MyST documentation](https://myst-parser.readthedocs.io/en/latest/syntax/admonitions.html). |
0 commit comments