add support for mkdocs

[WolfgangFahl]

as a committer of justpy i learned to know mkdocs recently and the pipeline to create a nice looking online version of md files seems to be straight forward. See e.g..

• https://justpy.io/
• https://github.com/justpy-org/justpy/blob/master/mkdocs.yml
• https://github.com/justpy-org/justpy/tree/master/docs

release_docs script of justpy project see https://github.com/justpy-org/justpy/blob/master/scripts/release_docs

#!/bin/bash
# WF 2022-09-19
# release a new version of the docs
mkdocs build
jp_dir=$(pwd)
docs_dir="$HOME/source/html/justpy"
if [ -f "$docs_dir" ]
then
  echo "$docs_dir doesn't exist"
  echo "please create it with"
  echo "git clone https://github.com/justpy-org/justpy --branch gh-pages --single-branch"
  exit 1
fi
cd "$docs_dir"
echo "syncing $jp_dir to $docs_dir ..."
rsync -avz $jp_dir/site/*  --delete .
git add *
git commit -a -m "new release by $USER"
git push

[gernotstarke]

I a recent discussion the Foundation-Level Working Group decided to align the glossary technology with the AsciiDoc & gradle pipeline already used for Foundation and most Advanced curricula.

Therefore I assume that most content contributors (actually the majority of terms has been provided via the Foundation curriculum) won't want a new toolset, but take the already existing.

It creates both pdf and a decent website "out of the box".

I propose to close this issue.

[WolfgangFahl]

I don't propose to make this the official release pipeline i just want to make local testing quicker. Currently i am experimenting with rsyncing the files to a doc directory and use

mkdocs build
mddocs serve

as outlined in: https://www.mkdocs.org/getting-started/

Since docs and site is in ".gitignore" this is just a local change and scripts/release_docs will warn you if no docs directory is there. We might want to rename the script then to "test_docs_withmkdocs" or the like if this shall be for local testing only.

[WolfgangFahl]

The fulltext search already works and seems to be helpful:

[programming-wolf]

I don't know if it's reasonable to spend so much time on this. With the template, you can also easily create the glossary locally, both as website and as PDF file.

[WolfgangFahl]

@programming-wolf Benajmin - thanks for looking into this. I always think it's a good idea to look into alternatives especially if it gives you new insights. See e.g. https://stackoverflow.com/a/54190808/1497139 showing that ".md" might have to be renamed to ".asciidoc" to display the source files natively in github. There are quite a few other issues that might be fixable much quicker using mkdocs than the existing pipeline.

For me it's not much extra effort - i am more interested in the content than the technology stack being used to create the glossary views.

[WolfgangFahl]

For now i am happy with the state of affairs. mkdocs can't replace the other pipeline yet but give a quick search and check capability.