Migrate openmage.readthedocs.io to Awesome OpenMage

[fballiano]

OpenMage's readthedocs has some basic info about the project and a list of modules/extensions, but it doesn't look very modern, the navigation is not really quick and most of all it has almost zero contributions.

This RFC aims to re-create the same "concept" with a different tool, which is considered a de-facto standard (the awesome format) which would provide a more modern look, an easier way for people to interact and contribute and overall a better image for OpenMage.

Direct link to the RFC page for easier reading:
https://github.com/fballiano/openmage-rfcs/blob/readthedocs/draft/0000-migrate-readthedocs-to-awesome-format.md

[elidrissidev]

I'm 100% with this. An awesome repository is so much easier to browse and maintain.

A point to add to the implementation:

• Add the awesome-openmage repository to awesome lists.

[Flyingmana]

do you have some awesome format examples for multiple pages?
Are there Reports on how they perform and how to optimize them for SEO?

How is it behaving with a growth in contributions and where are its limitations?
What Hosting possibilities does it have?

What are the advantages of the Awesome Format against the established documentation tooling of Sphinx which is a standard tool for close to 15 years and a core tool of the Python project?

[fballiano]

I'm 100% with this. An awesome repository is so much easier to browse and maintain.

@elidrissidev thank you!

• Add the awesome-openmage repository to awesome lists.

just added!

[fballiano]

do you have some awesome format examples for multiple pages?

no but I really don't think that it's meant to be multipage. for example the main awesome page is huge but still single page

Are there Reports on how they perform and how to optimize them for SEO?

I don't know of the existence of that kind of data

How is it behaving with a growth in contributions and where are its limitations? What Hosting possibilities does it have?

AFAIK everybody is keeping them on github, I wouldn't host it anywhere (the process could be cloning and rendering the markup or maybe using github pages if possible).

What are the advantages of the Awesome Format against the established documentation tooling of Sphinx which is a standard tool for close to 15 years and a core tool of the Python project?

I don't know the python world much but the point of the whole RFC is to make it modern and easier to contribute. As you can see here https://github.com/sindresorhus/awesome there are probably more than a hundred other awesome lists.

[Flyingmana]

I might be misunderstanding something, but for me it seems the awesome lists are like, just a simple link list. Its not Content, just an Index of where to find Content.
It is not intended to contain Documentation, Guides, Tutorials, Q&As, is it?
In the end its a single markdown File, served directly from the Github Repository in most cases.

I dont have anything against having this, but you want to use it as a Reason to remove a proper Documentation tooling, which supports already 100% of what you would do with an awesome list, even in the exact same format.

[fballiano]

I might be misunderstanding something, but for me it seems the awesome lists are like, just a simple link list. Its not Content, just an Index of where to find Content. It is not intended to contain Documentation, Guides, Tutorials, Q&As, is it? In the end its a single markdown File, served directly from the Github Repository in most cases.

it is mostly a list of links, but that doesn't mean we can't have some content sections, but it's usually very brief (like the one that I added in my awesome-openmage about the installation).

I dont have anything against having this, but you want to use it as a Reason to remove a proper Documentation tooling, which supports already 100% of what you would do with an awesome list, even in the exact same format.

but still nobody is contributing to the readthedocs because of the reasons in the RFC ;-)

[sreichel]

Maybe "awesome list" to link to resources, modules, documentatio, .... but use githubs wiki pages for content?

[fballiano]

Maybe "awesome list" to link to resources, modules, documentatio, .... but use githubs wiki pages for content?

I'm not entirely sure, is it possible for non-maintainers to open PRs for changes to wiki pages?

[sreichel]

I'd say yes, but lets test it.

[Flyingmana]

I'm not entirely sure, is it possible for non-maintainers to open PRs for changes to wiki pages?

githubs wikis only support direct write. No branching, no PRs. Just a simple wiki (with terrible navigation sidebar)

[sreichel]

You can clone wiki pages per project, why should PRs not work here?

Do we need branches for wiki pages?

[fballiano]

You can clone wiki pages per project, why should PRs not work here?

https://stackoverflow.com/questions/10642928/how-can-i-make-a-pull-request-for-a-wiki-page-on-github
seems it's not possible :-(

Do we need branches for wiki pages?

that's a hard no :-D

[sreichel]

This post is from 2012, maybe something changed ... https://docs.github.com/en/communities/documenting-your-project-with-wikis/adding-or-editing-wiki-pages#cloning-wikis-to-your-computer

[fballiano]

can you do something with this one? https://github.com/fballiano/openmage/wiki

[sreichel]

Seems not to work. I can see the diffs, but im not able to create a PR.

Okay, wiki page will not work.

[sreichel]

New candidate ... mkdocs?

[Flyingmana]

New candidate ... mkdocs?

readthedocs already supports mkdocs https://docs.readthedocs.io/en/stable/intro/getting-started-with-mkdocs.html

[sreichel]

I know. Tested mkdocs with readthedocs template.

[fballiano]

in my point of view we don't need to add other tools that few people know how to use.
a wiki page or a awesome repo it's extremely much more easy for everybody to contribute.

[sreichel]

in my point of view we don't need to add other tools that few people know how to use.

Can understand this, but ...

• wiki pages will not work
• awesome-list is only a list w/o navigation
• readthedocs require new rst-syntax
• jekyll has limited markdown

Im testing mkdocs and it really easy to use. All you need is ...

• install python3
• install mkdocs (+ plugins)
• run mkdocs build/serve

Pros

• uses markdown syntax, thats easy to extend
• modern look (with material or RTD theme)

Cons

• requires python (yeah, another "tool")

I'd also delete https://github.com/OpenMage/documentation and add its content to mainm repo, to make it easier to add documention.

[fballiano]

for the amount of doc that we have I still think an awesome list is enough.

EDIT: there's no problem with adding other tools, unless they make contributions harder for people, the awesome is the easiest way to get people to add stuff to the doc, which is somethat the never happens if we require tools to be installed etc.