Wiki Page

[kiatng]

We have added tons of features. For users and developers, new and old alike, it'll be good to have a wiki page to navigate all these cool features that cannot be found in the old User Guide and Developer Guide, and not answered before in stackoverflow and its sister site.

[sreichel]

Wiki pages are limited in structure. Thats why i've tried with mkdocs .... #3249

[kiatng]

The issue description requires some knowledge on the thing you propose, so I have no idea what it is about; but I'll take a look and investigate when I have the time.

[fballiano]

I like the wiki idea (as awesome-openmage could actually be a wiki page but I remember that this was already said somewhere (couldn't find anymore, I recall it was @Flyingmana but I could be wrong) but there were some limitations with the wiki, maybe about collaborating or versioning, something like that.

[sreichel]

That's it. Asked for re-opening wiki, but we did not b/c limitations.

[kiatng]

I just discovered there are 2 ways to host wiki in GitHub:

1. Wikis Examples of good wikis are listed here.
2. Pages See a demo here.

I have to admit I have close to no knowledge on the above. I see that https://www.openmage.org/ is built by pages. But there is no wiki section on it yet. May be we can start there, a section called something like Get Dirty and organize by sales, customers, adminhtml, etc.

[sreichel]

https://www.openmage.org/ is also made with "pages" ... see https://github.com/OpenMage/OpenMage.github.io

I'd prefer mkdocs over Jekyll b/c its more flexible.

[Flyingmana]

We had a similar discussion a while ago here: OpenMage/rfcs#9

I started 4 years ago a documentation repository at https://github.com/OpenMage/documentation
The idea was to have a place, which is separate from the main repository, so we can have more relaxed review requirements, and also to provide moderation, review and merge permissions more relaxed. Especially as this can be lead by technical writers who might not have any coding experience.(in theory)

Githubs own Wiki was used for a while, but and organizing content, as well as general functionality was limited. And access regulation was difficult.
(Also I think for endusers ending up on Github might not be the best option)

Using Readthedocs for hosting was primarily, so we dont need to fight with any build tools in the pipeline, also its an established hosting platform for documentation.
But with the underlying technology its easy to switch the hosting to a different place without big changes in our documentation.

The technology was started with is Sphinx https://www.sphinx-doc.org/en/master/index.html
using as content format reStructured text (its a bit older then markdown and offers more flexibility) https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst
I decided for Sphinx back then, because its an established documentation tool, used by a big community.
Its supporting rst, which is for example also used by the Symfony Docs. And as with markdown, its as easy as writing a text file. Actually it even supports markdown.

One example for Organizing Content we have
https://github.com/OpenMage/documentation/blob/main/modules/index.rst
which builds to https://openmage.readthedocs.io/en/latest/modules/index.html
Not only allowing dynamically to include multiple sub documents, but also listing included Sections of these documents.

The biggest Problem in the end was people having the time to provide new documentation.

If anyone has Ideas how to reduce the entry hurdle, Iam open for suggestions.

[sreichel]

I tried differnt thing,s but ended with mkdocs. Is there anything wrong with it?

[Flyingmana]

I did not check it much back then, as I was not aware of any projects using it.
Just wanted to document my whole knowledge and experience here and leave the decision to others.

[kiatng]

I should not have used "Wiki page" as title of this discussion. Wiki means document everything. However, what I actually meant was much less ambitious and much smaller in scope than a full-brown wiki; my intent was more like a section under it called something like "recipes", "how to", "examples" for the new or little known features of OpenMage. I apologize for the misunderstanding.

Here's an example of what an article of the page would look like:

Add dynamic block contents in category page

In backend > Catalog > Manage Categories, we can configure a category page and put it on the main menu. The page contents are rendered in

app\design\frontend\base\default\template\catalog\category\view.phtml

If we want to render an HTML table in which its data are taken from the database, we would follow these steps:

1. Create a custom block mymodule/mytable with template mymodule/mytable.phtml.
2. Whitelist our block for rendering in the frontend: backend > System > Permissions > Blocks
3. Create a CMS static block: backend > CMS > Static Blocks and set the Content to render from our block with this directive: {{block type="mymodule/mytable" template="mymodule/mytable.phtml"}}
4. Create a subcategory: backend > Catalog > Manage Categories > Add a subcategory and in the Display Setings tab, set the category attribute Display Mode to Static block only and CMS Block pointing to our block.

Voila, the HTML table is rendered under the menu we just created. However, every time the table in the database is updated, and because CMS blocks rendering are taken from the cache, we would need to refresh the cache.

What if the table is constantly being updated, or there is an expiry condition on some data which shouldn't be included? In which case, we would want to render the HTML table dynamically. It's actually quite easy to do:

1. In the subcategory page in backend, set the Description to this: {{block type="mymodule/mytable" template="mymodule/mytable.phtml"}}.
2. Continue on to the Display Setings tab and set the CMS Block to Please select a static block ....
3. In our config file, either in the module etc/config.xml or in the local.xml, insert the following:

<config>
    <!-- other config -->
    <global>
    <!-- other config -->
        <!-- copy the following and insert in your etc/config.xml or local.xml -->
        <catalog>
            <content>
                <tempate_filter>cms/template_filter</tempate_filter> <!-- Note the typo on template must remain as "tempate". -->
            </content>
        </catalog>

That's it, the table is now rendered dynamically. There 's no need to create the CMS static block.

[Flyingmana]

I copied this as is here OpenMage/documentation@456fde1

With this result: https://openmage.readthedocs.io/en/latest/guides/add_dynamic_block_contents_in_category_page.html

[kiatng]

OK, that works for me. Thanks. Now, we'll just need to fix the navigation, a template for guide: author, date, applicable versions, tags as a minimum. Is it possible to have a comment section like in PHP online manual?

[pquerner]

You can use https://utteranc.es/
That way comments work with your github account.

[sreichel]

OK, that works for me. Thanks. Now, we'll just need to fix the navigation, a template for guide: author, date, applicable versions, tags as a minimum. Is it possible to have a comment section like in PHP online manual?

• navigation ... managed in mkdocs.yml
• author
• date
• applicable versions (maybe via tags?)
• tags
• comment system via https://utteranc.es/ or https://giscus.app (@pquerner thanks)

Other nice to haves ... search, copy to clipboard for code blocks, better highlighting, "blog"-like functionality for guides, ... can be tested in local env, just install mkdocs.

No need for https://openmage.readthedocs.io nor duplicate code on https://www.openmage.org ... ?

[pquerner]

Thats fricking awesome!

[addison74]

Nice work

[Flyingmana]

sigh I hope that was not to much work yet. Comment systems are a point of risk, so they need to get vetted well.
There are first some basic questions regarding Moderation.
How does it prevent Spam, how to restrict allowed people to comment, how to make sure its not used to circumvent moderation. What additional Block options are there (as we can not report this with Github, as they will delegate to utterance as they are the one posting)

Then in comparison, its using Issues, right? Can it use also the Discussion feature, as https://github.com/giscus/giscus is doing? (not saying it would be better)

How well is it suited against XSS attacks?
Is the interaction for writing directly between browser and Github, or is it going over a middleman?
How well is their access token protected?

[pquerner]

regarding security, its as good as the commit section on plain github.
moderation would be the same as any issue posted in any repository - you're on your own. no "pending verification" stuff.

[sreichel]

@Flyingmana changed to giscus.