Workflow to update help documents

[UlrichB22]

The help documents in the “help-en” namespace and the user documents provided in readthedocs, for example, contain redundant information. In particular, the documents “src/moin/help/help-en/rst.data” and “docs/user/rest.rst” are identical.

We need a well documented workflow how to update those docs.

[UlrichB22]

The online help documents in the wiki namespace “help-en” should always be updated via the MoinWiki frontend to avoid inconsistent metadata. I recommend the following workflow.

To ensure that you are using the latest help documents from Git, create a new temporary Moin-Wiki. Create a new empty directory and change to it with cd.

cd <new-wiki-dir>
moin create-instance --full

To enable help documents to be updated, modify the new wikiconfig.py file. In the acls-Dict for the help-en namespace, change default="YOUR-TRUSTED-EDITORS-GROUP:read,write,create All:read", to default="YOUR-TRUSTED-EDITORS-GROUP:read,write,create All:read,write,create", This configuration is only intended for use in a temporary private wiki.

Start the Buildin server and open the front end in a web browser at http://localhost:5000/

moin run

Update any item in help-en. When you are finished, run the following:

moin maint-reduce-revisions -n help-en
moin dump-help -n help-en

Change your working directory to your moin Git repo and check for the updates with

git diff

If you have updated the help-en/rst item, you must also update docs/users/rest.rst. You can simply copy it.

cp -p src/moin/help/help-en/rst.data docs/user/rest.rst

Now you can add, commit, and push your changes in Git.

[UlrichB22]

@gmilde, I don't think a symlink between these 2 rst documents will work in any situation. This will need further investigation and proper testing.

[gmilde]

The online help documents in the wiki namespace “help-en” should always be updated via the MoinWiki frontend to avoid inconsistent metadata.

Alternative workflow:

Update the help file in the repo (e.g. src/moin/help/help-en/rst.data)

Create a new "dummy" wiki and load the help files:

 cd dummywiki
 rm -rf wiki
 moin create-instance
 moin index-create
 moin load-help -n help-en
 moin load-help -n help-common

Check/Fix meta-data::

 moin maint-validate-metadata --all-backends --verbose
 moin maint-validate-metadata --all-backends --fix

Dump all the English help files to the version controlled directory::

moin dump-help -n help-en

This may be simpler for the fixing of small typos or with documents that are duplicated in "wiki-internal" and "Sphinx" documentation.

[gmilde]

Additional problem:

How to load updated help docs into an existing wiki?

A local wiki, which I set up in Oktober has a set of pages to test current behaviour and modifications...

Re-loading help files into this wiki with

   moin load-help -n help-en

does not update files that changed in the repo :( (Files that are manually deleted using the wiki interface are re-loaded.)

When dumping the help files from this wiki, changes in the repo help files (done by other developers) are reverted to the version from 2025-10-19.

I'd prefer if moin load-help would also update existing files.