Expose and restructure the documentation

[Zeitsperre]

The documentation can be viewed inline when browsing on Github or on ReadTheDocs https://birdhouse-deploy.readthedocs.io.

Convert all .md files to .rst files so they can be used on ReadTheDocs.

Due to the hybrid goal (view doc both while browsing Github and on ReadTheDocs), some compromise had to be made:

• all the relative links to other files in this repo are only working while browsing Github, not on RtD

• a "download" link is added to all those relative links for RtD, but annoyingly those "download" link are also visible while browsing Github but not working

The current state is not perfect. We'll try to address the "relative links" vs "download links" work-around to have hybrid doc both when browsing Github and on ReadTheDocs another time.

[crim-jenkins-bot]

Can one of the admins verify this patch?

[tlvu]

Github browsing still broken with relative links.

You should be previewing the changes directly on Github and not in your IDE I think, so you can catch these errors faster.

[tlvu]

The links in RtD is also broken. ex: https://birdhouse-deploy--118.org.readthedocs.build/en/118/birdhouse/pavics-compose.sh.

[Zeitsperre]

Went in a different direction and decided to make the GitHub links work by default, with the option of downloading a given file (they're copied to RtD as downloadable files). If we want, I can go in and replace all download links with the URL to these files on GitHub, but because they aren't markdown or rst's, getting them to display as raw content is only viable with the :download: approach.

[tlvu]

Also from here https://birdhouse-deploy--118.org.readthedocs.build/en/118/, all the README links also do not resolve.

[tlvu]

Why not just keep the original text "How to deploy the entire PAVICS platform, see the following README pages:" ... cuz it reads weird if user is actually on Github.

[Zeitsperre]

I mention GitHub here because on RtD, clicking these links won't work, last I checked.

[tlvu]

Oh true, those "download" links works on RtD https://birdhouse-deploy--118.org.readthedocs.build/en/118/deployment.html

[Zeitsperre]

So I had a thought last night: GitHub navigation requires Markdown-like references (`LINKNAME <relpath/to/non-rst-file>`_), while RtD/rST needs urls (`LINKNAME <URLrelpath/to/non-rst-file>`_). If there were an easy way to template the URL to these relpaths when building the docs? Maybe Jinja2 could help with that? Maybe this is a bit much.

EDIT: This would be overkill. I'm happy with the layout as it is. GitHub's functionality is primary. RtD navigation and file downloads work. @tlvu What I need to know is do we set links to the CFG/YAML/JSON files on GitHub or do we copy them to RtD and serve them from there?

[tlvu]

What I need to know is do we set links to the CFG/YAML/JSON files on GitHub or do we copy them to RtD and serve them from there?

I would prefer copy to RtD and serve them from there so it is snapshotted. If we link to GH from RtD, I wonder how do we lock down the version (ie if RtD was built by changeset1, how do we link to the files on GH at changeset1 and not master that is constantly changing).

By the way, I think we can accept having the :download role showing up when browsing GH for now. We can revisit later. I feel bad you spend too much time on this already.

So if you can copy the files to RtD so the relative links work both on RtD and GH and we can remove the annoying :download role, that would be best. If that seems like another rabbit hole, we can stop here.

[tlvu]

By the way, if we are going to keep the :download role trick, https://github.com/bird-house/birdhouse-deploy/blob/master/birdhouse/components/README.rst is missing them.

[Zeitsperre]

I would prefer copy to RtD and serve them from there so it is snapshotted. If we link to GH from RtD, I wonder how do we lock down the version (ie if RtD was built by changeset1, how do we link to the files on GH at changeset1 and not master that is constantly changing).

Short answer: It would be a huge pain to do this. We'd need to add commit hashes to everything, which would be feasible with Jinja, but a nightmare to maintain. Maybe there's a better way, but I don't know it.

By the way, I think we can accept having the :download role showing up when browsing GH for now. We can revisit later. I feel bad you spend too much time on this already.

It's fine, I needed the practice. I'm just glad it's nearly done.

So if you can copy the files to RtD so the relative links work both on RtD and GH and we can remove the annoying :download role, that would be best. If that seems like another rabbit hole, we can stop here.

The only way to do that would be to convert all the non-rst/md files to HTML source files using a different converter (vanilla Sphinx doesn't support this out of the box). It's worth looking into but not today.

[tlvu]

@Zeitsperre What was this symlink for again?

[Zeitsperre]

Ah, it was to address the file access problem. I was exploring symlinking into the docs folder all the files I needed, but looks like you took a different approach. Looking at it all now.

[tlvu]

My other "approach" only works for files in birdhouse/ folder only, all other files still need the "download links" trick. So no nothing new, no change of direction.

[Zeitsperre]

It would be interesting if we could use hard links both in /birdhouse and under /docs/source/, but that might cause issues in other ways.

[tlvu]

It would be interesting if we could use hard links both in /birdhouse and under /docs/source/, but that might cause issues in other ways.

Not sure how this is going to solve our relative links on Github not working on RtD problem. What we really need is either

• a way to copy files into the html output folder at any location we want (the option I found in db4d5aa only copy to the root of the html output folder)

• a way to instruct RtD/Sphinx to rewrite all relative links to absolute link to Github at the same changeset of the build on RtD (ex: a relative link like ../env.local.example should be replace with https://github.com/bird-house/birdhouse-deploy/blob/COMMIT_HASH_OF_RTD_BUILD/birdhouse/env.local.example

[tlvu]

I don't like the download link work-around but this will be for another day.

[tlvu]

@Zeitsperre Check db4d5aa I found a way to directly copy some files to the html output but it only copies to the root, we are unable to specify any destination hierarchy.

Pretty much the only feature missing to have relative link working both while browsing Github and on RtD !!!