Documentation builder

[multimeric]

I'm thinking we should have a github pages website for MegaQC to compile the docs more neatly.

Sphinx is one option. It has the advantage of autodoc, but since MegaQC is an application and not a library this isn't a huge drawcard. The upside and downside is needing to use RST for most things.

Another option is mkdocs, which lets us retain the markdown format, and is somewhat simpler to configure.

[multimeric]

@ewels thoughts?

[ewels]

Yes! I have megaqc.info already but didn't get to building much besides a skeleton yet.

Most projects I just build custom sites using PHP with markdown rendering. I used Hugo recently though and really liked it, so maybe Hugo + GitHub Pages could be good?

Autodoc docs are good if we want people to tie into the code and use the functions directly? But for me that would be a secondary thing, if at all. So I'd prefer stand-alone "prose" docs as the first line of documentation.

Phil

[multimeric]

I think a markdown-based static-site generator would be good. If we host it on GitHub pages that would be easy to integrate into the Actions build. And then you can attach the megaqc.info domain name to that.

Hugo is probably fine, but I thought of two more potential upsides to Sphinx that don't involve autodoc: we can use it to document the CLI using sphinx-click, and we can document the API using httpdomain using Sphinx's ability to introspect the Python code. Of course both of these things are doable without Sphinx, but harder.

In terms of the structure of the site, I think we might as well follow the structure of the markdown docs that I've written up.

[ewels]

Sounds good! I don't have much experience with Sphinx but happy to go with whatever. As long as it looks pretty 😅

Let me know if / when you'd like me to set up the domain or do anything else.

[Zethson]

I am hosting lots of documentation using Read the Docs:

e.g. https://mlf-core.readthedocs.io/en/latest/readme.html

Source: https://github.com/mlf-core/mlf-core/tree/master/docs

I could set that up very quickly with my other projects' setups.
They are however based on restructured text files (*.rst) and not markdown.

If you would be happy with Read the Docs I could set it up based on restructured text files or if you insist also on markdown files. It should work somehow, since I have heard of people doing so. This is sphinx based stuff.

Cheers

[ewels]

Sounds good! I think RTD with markdown is pretty easy if you're self building / hosting, so I would prefer to stick with that.

I'd also quite like to make it look not like RTD and have its own theme. But that is not very important and can come later "when I have time" 👀😅 (of course if anyone else enjoys this stuff then go ahead)

[multimeric]

Sphinx does support markdown quite well, hopefully it doesn't cause any trouble with the heavy use of directives that it might require to implement the above features. I guess we have to weigh the accessibility of markdown against the power of RST.

With regards to hosting, though. I still don't quite understand what RTD gives us over just using GitHub pages and Sphinx?

[ewels]

Ah sorry, I tend to mix up RTD / Sphinx. Yeah, I'm keen for GitHub pages.

Also happy to switch to whatever format if markdown is a problem.

[Zethson]

RTD is pretty much first class supported by Sphinx. By the way you can use custom domains with RTD.
https://docs.readthedocs.io/en/stable/custom_domains.html
I've never tried to host a Sphinx based project with GH pages, but it should be technically possible (source: mighty internet).

Think I got the requirements down now.

• GH Pages for hosting
• Sphinx for building etc
• Markdown if possible
• Custom css somewhen later down the road.

Please assign the issue to me if everything is fine.

[multimeric]

RTD also has ads, fwiw

[Zethson]

Things that I never notice thanks to ublock origin. But yeah, let's go for Pages then.

[multimeric]

Oh also, if we do go with Sphinx + Github Pages, I wonder if there's any need for the separate MegaQC_website repo at all. I tend to just throw it under docs/ in the main repo as per Sphinx convention.

[ewels]

Yup, happy to delete MegaQC_website if it's not needed (but did we say that we wanted a flashy landing page in addition to the sphinx docs? where does that go?)

@Zethson if it helps, the nf-core/tools API docs are built here using Sphinx: https://github.com/nf-core/tools/blob/master/.github/workflows/tools-api-docs.yml

That's build into a dedicated branch: https://github.com/nf-core/tools/tree/api-doc and then rendered at https://nf-co.re/tools-docs/

I guess that we could use a similar approach, with a gh-pages branch on the repo?

[Zethson]

Let's discuss the website in another issue to keep this issue on topic: MultiQC/MegaQC_website#2

@ewels I'll have a look and will try some things out before committing hard on something that may not be what you want :)

[Zethson]

Draft PRs for mkdocs and Sphinx with Markdown are up:
#152
#149

Both have advantages and disadvantages, which I quickly jotted down.
How do you suggest to move forward?

[multimeric]

I'm of the opinion that having automated CLI and API docs is a huge boon, so Sphinx is still an easy winner for me. I can't see a lot of issues with your markdown + Sphinx setup, but I'm happy to move to fully RST if there's something to be gained there. I suppose if we had a manual Swagger API docs then Sphinx loses some of its appeal but that would be a decent amount of work I think.