doc: Add Markdown files

[wenzeslaus]

This is equivalent of OSGeo/grass#5057

This needs to be rebase merged without squash as two commits:

• doc: Rename .html to .md
• doc: Add .html files back

(The actual full commit messages will go to the base branch this time.)

Workflow

Set up a local repo for contributing:

git clone [email protected]:OSGeo/grass-addons.git
cd grass-addons
pre-commit install
# setup upstream and fork as needed

Get list of all HTML files:

git ls-files | grep -E ".html$" > ../all_addon_html_files.txt

Rename .html to .md:

while read -r FILE; do git mv $FILE $(echo $FILE | sed -e 's+.html$+.md+g'); done < ../all_addon_html_files.txt

Commit, but skip pre-commit with --no-verify (no fixes here, just pure rename):

git commit --no-verify -m "doc: Rename .html to .md

This is the first step in conversion of files with HTML documentation to Markdown.
It makes Git keep the history, esp. blame, for the Markdown file.

It does not touch r.landscape.evol which already has documentation in Markdown.
"

Repeat the four following steps as needed until pre-commit passes with no fixes or complains:

pre-commit run -a
git restore .
# edit .markdownlint.yml (in your favorite editor)
git add -p

Now amend the original commit, but this time let pre-commit verify the changes:

git commit --amend -m "doc: Rename .html to .md

This is the first step in conversion of files with HTML documentation to Markdown.
It makes Git keep the history, esp. blame, for the Markdown file.

It does not touch r.landscape.evol which already has documentation in Markdown.
"

Get the .html back:

while read -r FILE; do cp $(echo $FILE | sed -e 's+.html$+.md+g') $FILE; git add $FILE; done < ../all_addon_html_files.txt

Our list contains r.landscape.evol, but that already has a Markdown file, so we won't be destroying its HTML file either:

git restore --staged src/raster/r.landscape.evol/r.landscape.evol.html
git restore src/raster/r.landscape.evol/r.landscape.evol.html

Commit the .html files:

git commit -m "doc: Add .html files back

HTML will be in place as long as needed, but the primary, canonical file is the Markdown file.

It does not touch r.landscape.evol which already has documentation in Markdown.
"

Push.

To merge, I will enable the Rebase and merge option and merge with that.

Disable the Allow rebase merging option.

[wenzeslaus]

Blame on GitHub shows the "rich" history for .md:

https://github.com/OSGeo/grass-addons/blame/e14c942f400ff67b4ec0cef6074a22127d1f45ac/src/db/db.join/db.join.md
https://github.com/OSGeo/grass-addons/blame/e14c942f400ff67b4ec0cef6074a22127d1f45ac/src/db/db.join/db.join.html

Commit history where GitHub shows the rename for .md (with a link for more history) and uninterrupted history for .html (no renames).

https://github.com/OSGeo/grass-addons/commits/e14c942f400ff67b4ec0cef6074a22127d1f45ac/src/db/db.join/db.join.md
https://github.com/OSGeo/grass-addons/commits/e14c942f400ff67b4ec0cef6074a22127d1f45ac/src/db/db.join/db.join.html

Local Git gives similar results.

[echoix]

I assume the older grass8 will work correctly as it has access to html files too.

When it comes time to update addons docs, which are the source of truth? What is the guidance to update the HTML if a markdown is updated?

[wenzeslaus]

I assume the older grass8 will work correctly as it has access to html files too.

Yes, I assume that too :-) I'm reasonably sure actually.

When it comes time to update addons docs, which are the source of truth?

Markdown is the source of truth, i.e., it should be always updated.

What is the guidance to update the HTML if a markdown is updated?

HTML can be updated if the contributor wants good support for <=8.4.

I suggest to just address this per-PR and having this PR comment to be the official info for now. We can include some info into an announcement for the new doc, but I don't see much use in trying to reach potential contributors before that.

[echoix]

It's fine with me, I wanted to see it written somewhere to refer to, as I wasn't involved too much in the design of the new docs