Some points:

• build directory included
• maybe leave the markdown and use a sphinx extension: https://www.sphinx-doc.org/en/master/usage/markdown.html - this will be a lot less churn
• consider deploying a specific website github pages-only repo then we can also add the historical versions of the manual in the same place (need to check what domains are used and whether we need to redirect old domains to sub-directories)

Some points:

* build directory included

* maybe leave the markdown and use a sphinx extension: https://www.sphinx-doc.org/en/master/usage/markdown.html - this will be a lot less churn

* consider deploying a specific website github pages-only repo then we can also add the historical versions of the manual in the same place (need to check what domains are used and whether we need to redirect old domains to sub-directories)

1. build dir 👍
2. I did that when I started working on this but the problem is that the the .md files essentially remain as is so the look is the old wiki not the goal of the PR which is to harmonize (unless I missed something), so running the .md through pandoc to convert them to .rst was the only way to maintain the look that matched the manual.
3. will do, I am just trying to get through the conversions and formatting first then will get your's and Pete's input as to where we want to put things.

When I get some time to finish off the formatting issues (thi sweek hopefully) I will convert this PR back from draft for you to have a look at.

I was thinking with my point 2 suggestion that using that sphinx extension allows you to leave the markdown content as-is (i.e. it does the conversion from md - as well as any rst) but render it in whatever sphinx theme we want.

ok I will check again because this was months ago that I had tried it maybe I missed something

Here's another repo that builds its docs from .rst, .md, and .ipynb files. It's conf.py file might be an example. Also visit the repo's pyproject.toml for the dependencies.

I must have missed something when I first looked at this its been so long I thought it was "the look" didn't change but the look is correct, regardless I am able to build the docs using myst_parser but there are numerous issues though, for instance the local file links do not render the href in such a way that the links work, instead it treats the local link as an anchor to the file it is referenced in. For example this is how myst renders the link specified in the .md:

* [Facilities](Facilities.html "wikilink") using NeXus

As:

<li><p><a class="reference internal" href="#Facilities.html"><span class="xref myst">Facilities</span></a> using NeXus</p></li>

I spent the better part of the morning trying to configure myst_parser to treat the links as local links but no joy, the only way i was able to solve it was to have a function connected to app.connect('build-finished'...) walk all the generated html files and remove the '#' character from the href=. This approach works and does produce html files with links that work but during the sphinx build there are a ton of WARNING: 'myst' cross-reference target not found: warnings (among others) that is just one example.

I have been approaching this from a build without warnings/errors but maybe I should ask do we care about warnings during the build? if not and we only care about functioning web pages then that would make this task much quicker, for me anyway.

With the way I had been doing it (converting all .md to .rst) I am nearly done making all the files look nice (straight pandoc conversion from .md to .rst is not very readable), so I would prefer to just finish that off as opposed to trying to retain the .md files and sort out all of the issues which I don't think is going to save me any time, plus I had organized the files into some semblance of order as opposed to everything in the content directory which I also prefer.

I freely admit that I'm no expert on this stuff so I don't have a problem if you guys want to take a crack at using the .md files I just think i am closer to being done the initial way and it more closely mirrors the manual documentation in terms of repo structure.