rST documentation fixes, part 1: preparation

[gmilde]

Simplify the markup and merge changes in the rST markup help, so that
/docs/user/rest.rst and moin/src/moin/help/help-en/rst.data are again in sync.

More extensive updates/fixes to follow.
Can we use a symlink instead of manually maintaining 2 files?

[gmilde]

The error is:

FAILED src/moin/cli/_tests/test_modify_item.py::test_dump_help - AssertionError: /home/runner/work/moin/moin/src/moin/help/help-en/rst.meta != my_help/help-en/rst.meta

A different meta-data should be expected when the PR changes a help file.
Unfortunately, I don't know how to get out of this deadlock.

The Developer documentation on updating the help docs only helpf if you change the file via the Wiki editor but does not tell how to get updates made directly to the files in src/moin/help/help-en/rst.data into a test wiki instance.

[UlrichB22]

@gmilde, thanks for your work.

Meta data and the index are only valid if you edit the file via wiki editor. The preferred method would be to create an initial wiki using 'moin create-instance --full' in an empty directory, update the item using the frontend and follow the instructions from documentation. You need to copy the raw item and the meta file to your git source. Editing wiki items in the file-system will give unpredictable results.

[gmilde]

Meta data and the index are only valid if you edit the file via wiki editor.

For my local wiki instance, I could fix the metadata with

moin maint-validate-metadata -avf

However, dumping the help with

moin dump-help -n help-en

reverted all changes to the repo that were done after the creation of the local wiki instance (mine, as well as commit c418213).

I could work around this by creating one more local wiki instance,
running moin maint-validate-metadata -avf and help/help-en/rst.data in this instance. The "fixup" commit containes the updated metadata as well as a fixed file path.

However, IMO it's sub-optimal that all changes to the help files by other developers need a re-creation of local wiki instances or manual updates for every changed repo help file.

[UlrichB22]

I will test the workflow to update help-files the next days.

[gmilde]

I will test the workflow to update help-files the next days.

Maybe we can even remove the help meta-data files from the repo and let moin create them when loading help files the first time.

[gmilde]

Please also advise, whether one of the duplicate files /docs/user/rest.rst and moin/src/moin/help/help-en/rst.data can be replaced by a symlink (and, if yes, which).

[UlrichB22]

Follow-up in #2013.