Docs

[Tom-Willemsen]

Overview

https://isiscomputinggroup.github.io/ibex_developers_manual

Changes in this PR

• Merges in the entire git history of the .wiki git repository (~11k commits).
  • This means that pages retain their history information and it is possible to use usual git blame functionality to find who/when changed a line.
• Restructures the pages on the filesystem into a hierarchical structure, grouped by topic.
  • The overwhelming majority of pages have been moved to their new folder with minimal content changes (e.g. just minor formatting changes as required & removal of manual breadcrumbs since these now get automatically inserted).
  • Where structure already existed (via manually added breadcrumbs) on the "old" wiki, this has generally been kept. For example the pages under "specific iocs" are in a tree which largely mirrors the manual structure on the old wiki. Occasionally the structure has had to change slightly to accomodate pages which were not previously in any structure, or to ensure that the navigation structure didn't become too deep.
  • Pages which only existed as indices have been replaced with auto-generated indices, for example this page on the "old" wiki now looks like this in source code and renders like this.
  • In a very small number of cases, paragraphs have been moved from one page to another to make them sit properly in the structure. However I have attempted to keep this type of refactoring limited in this PR - future PRs may refactor pages further.
• Uses sphinx to render that new restructured document tree into a navigable set of HTML pages.
  • sphinx is a standard, widely-used documentation tool - see e.g. Linux kernel docs, Python docs, EPICS docs - all of which are using sphinx. This means it can scale well even for very large/complex projects.
  • Sphinx ensures we cannot have "orphan" pages - all pages must be reachable via the navigation structure
• Moves images & linked documents so that they are now next to the page(s) that primarily use them
• Fixes-up the internal links & image references (including those that were previously hardcoded to point at https://github.com/isiscomputinggroup/ibex_developers_manual/wiki and images that were previously being loaded from hardcoded URLs)
  • Sphinx will now do a check of internal/image links as a normal part of build - this replaces the internal-link checking functionality that was previously implemented by WikiChecker
• Implements spell-checking as part of an on-push CI, and fixes up places where the spellchecker flagged typos
  • Sphinx will now do a spellcheck as a normal part of build - this replaces the spell-checking functionality that was previously implemented by WikiChecker
• Documents how this "new" wiki is built and how to edit it, how to build it locally, how spellchecking works, and so on.
  • https://isiscomputinggroup.github.io/ibex_developers_manual/Editing-the-Wiki.html

Notes

• Sphinx has a linkcheck plugin for checking external links. I have a branch that configures this, but have not enabled it in this PR, as we have a lot of broken links (our existing WikiChecker equivalent, for external links, also gets ignored...)
• For mirroring on shadow, we would now use the same mechanism that genie docs use (i.e. git pull of the gh-pages) git branch which gets the full rendered HTML). This means that:
  • We no longer need to use Gollum, which has historically not rendered the wiki very well - for example
    • Try clicking some links from https://shadow.nd.rl.ac.uk/ibex_developers_manual/The-GUI
    • Try expanding the "jump to section" dropdown on https://shadow.nd.rl.ac.uk/ibex_developers_manual/Reflectometry-Config-Training-%E2%80%90-Exercise-1.md
  • We will now be able to serve the exact same HTML on github pages and on shadow
  • It renders properly in the embedded internet exploder view in the client
• This enables us to create PRs on the wiki. My suggestion is that we don't enforce making every change go via a PR, but rather let people use their judgement:
  • Correcting typos -> just commit to master/self-merge PR
  • Adding a few new sentences -> self-merge PR or flash review
  • Adding new pages e.g. as part of a ticket -> make it a PR to be reviewed as part of the ticket
  • Restructuring / rewriting / significant changes -> Make a PR
• If/when merged, I will create a nightly CI job so that we spot any build/spelling problems at standup (in addition to the on-push CI that will email the perpetrator within a minute or two of pushing a typo)
• If/when merged, I will push commits to "old" wiki replacing pages with a pointer to their new location - so that we don't have duplicated content. This means that old links will still "work" in some sense.

---

HEAD commit before this PR is merged is 709cf16267964ebfde4485266da1fe545af812ef (tagged as pre_wiki_merge)

[Tom-Willemsen]

Group code reviewed by @FreddieAkeroyd @Chsudeepta @danielmaclaren @rerpha @jackbdoughty @LilithCole @esmith1729 @LowriJenkins @davidkeymer @iangillingham-stfc @ChrisM-S and the consensus was to merge and try this.