Add initial sphinx doc site for RTD

[michaelpj]

This sets up an initial sphinx doc site that we can use with RTD. I would need some help from a repository admin to get it building on RTD itself, but you can build the site locally:

nix-shell
cd docs
make html
firefox _build/html/index.html

I moved all the content from the README to the docs, with the intention being to eventually just link to the RTD site from the README. Otherwise I haven't touched the content, apart from fixing a few links and header depths. There's a lot more organization etc. that we could do, but probably better to do that after we have an initial version.

I set up sphinx to use markdown, since I know people like that. The exception is the index pages, which I think need to be in RST for the toctree definitions. I do like RST, especially for better cross-reference, but the markdown version seems to work fairly well.

Fixes #2033.

(cc @berberman since I had to fiddle with the Nix stuff a bit)

[pepeiborra]

You are an admin now

[michaelpj]

Okay, I set up the build and it builds PRs too, so you can see a link to a preview from the PR status.

[michaelpj]

I should add some instructions about how to build the doc site into the docs

@jneira I'm afraid I don't know what to do about Windows. I think you should "just" need to install python and the required packages however you do that... There is this little requirements.txt I had to make for RTD, perhaps you can use that and pip or something?

[jneira]

yeah don't worry, with a little bit of luck it only will need some python setup
A install guide would be great, will update it with the windows part

[michaelpj]

Okay, I added a section about building the docs. I think this is good to go if we're happy with how it looks and we want to go with RTD.

[jneira]

I've added the make.bat auto generated by sphinx-quickstart, but it is failing at a first blind attempt:

PS D:\hls\docs> .\make html
Running Sphinx v4.1.2

Extension error:
Could not import extension myst_parser (exception: No module named 'myst_parser')

[jneira]

pip install myst-parser && pip install sphinx_rtd_theme did the trick

[michaelpj]

I think you just need to do pip install -r requirements.txt

[michaelpj]

I'll add that to the doc.

[michaelpj]

Done

[jneira]

docs looks fantastic, many thanks to spend time on this, documentation usually has not the attention it deserves so i value specially pr's like this, congrats!

[jneira]

I moved all the content from the README to the docs, with the intention being to eventually just link to the RTD site from the README

Mmm not sure about this, i would like to see some brief content in the README, no a copy from the full docs but a resume or something for those who want to take a quick look

[jneira]

The nix build (not required though) is failing with

 error: builder for '/nix/store/31wvaghxbj402a1f1nl82mz1rrrr2az8-ormolu-0.1.4.1.drv' failed with exit code 1;
       last 10 log lines:
       >
       > src/Ormolu/Printer/SpanStream.hs:17:1: error:
       >     Could not find module ‘SrcLoc’
       >     Use -v (or `:set -v` in ghci) to see a list of the files searched for.
       >    |
       > 17 | import SrcLoc
       >    | ^^^^^^^^^^^^^
       > [ 7 of 48] Compiling Ormolu.Processing.Common ( src/Ormolu/Processing/Common.hs, dist/build/Ormolu/Processing/Common.o, dist/build/Ormolu/Processing/Common.dyn_o )
       > [ 8 of 48] Compiling Ormolu.Processing.Cpp ( src/Ormolu/Processing/Cpp.hs, dist/build/Ormolu/Processing/Cpp.o, dist/build/Ormolu/Processing/Cpp.dyn_o )
       > [ 9 of 48] Compiling Ormolu.Processing.Postprocess ( src/Ormolu/Processing/Postprocess.hs, dist/build/Ormolu/Processing/Postprocess.o, dist/build/Ormolu/Processing/Postprocess.dyn_o )

[michaelpj]

Mmm not sure about this, i would like to see some brief content in the README, no a copy from the full docs but a resume or something for those who want to take a quick look

Yeah, not sure what to do about this. It would be nice not to repeat ourselves. Maybe we can write a section that we can include into both? There's not much introductory prose at all even in the current docs, just a sentence.

Maybe I can link to a few specific interesting sections like "features", "building the code", "contributing guidelines".

The nix build (not required though) is failing with

It's broken on master in the same way 🤷