Get Github to generate previews of docs content (change .txt files to .rst)
mradamcox opened this issue · 3 comments
describe the issue
Currently we have Restructured Text content stored in .txt files. While this is properly rendered by Sphinx, Github doesn't recognize .txt files as restructured text so it only displays the raw file content. I was just looking at the QGIS website repo (e.g. https://github.com/qgis/QGIS-Website/tree/master/source/site/about) and realized that their .rst files are properly previewed by Github. So we should switch all of our files to .rst extension.
Being able to preview the markup directly in Github will make it much easier for quick edits and new editors to understand how their changes to the docs will appear in the readthedocs deployment.
which release does this issue concern?
just change the main branch, maybe 5.1 as well??
Just did a quick test on a temporary branch and changing the extension of a file to .rst and adding '.rst' here https://github.com/archesproject/arches-docs/blob/master/docs/conf.py#L42 does work as expected.
Big downside to this is that git history is lost, because the original file is deleted and a new one created in its place. This may be a big enough drawback to abandon this idea.
Closing, as I think enough guidance now has been added in the README and else to point people to creating new files in .rst. This should slowly move us to the goal of this ticket without having to lose the git history on every file all at once.