search

archesproject / arches-docs

official repo for Arches documentation
https://arches.readthedocs.io
9 stars 21 forks source link

Get Github to generate previews of docs content (change .txt files to .rst) #255

Closed mradamcox closed 2 years ago

mradamcox commented 3 years ago

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??

mradamcox commented 3 years ago

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.

mradamcox commented 3 years ago

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.

mradamcox commented 2 years ago

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.