Retropie-setup: Make Wiki Prettier

[HerbFargus]

The wiki is fantastic. I like it a lot. but per our earlier discussion there are a few things we can do to improve the design of the wiki so it looks a little cleaner.

Here are a few examples:

Sphinx:

Borg Backup
https://borgbackup.readthedocs.io/en/stable/
github repo: https://github.com/borgbackup/borgbackup.github.io
Qgis
http://www.qgis.org/en/docs/index.html

Mkdocs:

https://mkdocs.readthedocs.io/en/stable/

I think they should be able to be hosted on github with github pages (powered by jekyll of course)

I don't think we should do away with the github wiki by any means as it is nice to be able to rely on the community for wiki updates but one way would be to have a conversion script of sorts

There is some discussion on it here:
http://stackoverflow.com/questions/25578928/rendering-a-github-wiki-on-a-github-pages-jekyll-site

Basically the script will create wiki pages with proper liquid tags for jekyll. unfortunately the examples are broken but it should still be a doable thing. We can rerun the script whenever we need to, to regenerate the docs from our wiki.

github repo here: https://github.com/djacquel/WikiToJekyll

I'm sure there are other ideas too, I'm open to any good ideas. there are a few things on the wiki that may need some work (mame being one of them)

[joolswills]

I guess the first step would be to do an initial conversion and see how it looks out of the box. If it can be done with a fully automated process, it would be worth it (to have a prettier read only copy of the documentation hosted on the site or on github).

[HerbFargus]

just another discussion on something called prose but perhaps may not necessarily be the route we want to go.:

https://bugherd.com/blog/building-a-better-github-wiki/

[HerbFargus]

alrighty, first proof of concept with mkdocs and the readthedocs theme hosted on github pages:

https://herbfargus.github.io/wikitest/

I just manually added a few configs in the yaml just to see if I could get it working

I used this guide:

https://mkdocs.readthedocs.io/en/stable/

This guide seems to suggest we can use submodules instead of manually copying and cloning which may be a better option for keeping parity with updates:

http://www.embeddedlog.com/static-docs-from-github-wiki.html

I'll have to make some tweaks to the github wiki and fix some of the headings and images- also may have to look at how the links convert but I think its very doable.

[HerbFargus]

Here is a quick update:

https://herbfargus.github.io/RetroPie-Docs/

I want to see if there is a way to make the headings collapsible like the borgbackup docs but it looks like they are using sphinx hosted on readthedocs whereas my approach uses the sphinx readthedocs theme with mkdocs hosted on github pages.

Sphinx utilises rst (restructured text) whereas the github wikis are written in .md (markdown) so I am not sure how many extra functions like the toctree collapsing carry over to mkdocs and github pages- I would like to avoid using rst if at all possible to keep wiki parity simpler.

Further discussion here: https://github.com/mkdocs/mkdocs/issues/588

I'm still looking at options, might be worth checking out other themes, there is some discussion on collapsible headings on the material theme https://github.com/squidfunk/mkdocs-material/issues/14 might be worth checking out

[HerbFargus]

Also just putting this out here as a note for me. found a tweaked readthedocs theme that incorporates collapsible menus: https://github.com/Helpmonks/docs I will merge in the pending PR on it and see if I can build it and if it will play nice with github pages and mobile. may need a bit of refactoring

[markwkidd]

@HerbFargus I have worked some on the Lakka documentation which is automatically generated from its github wiki pages. I thought I'd mention this in case you weren't aware, since I assume Kivutar and gouchi would be willing to share their setup.

For example:
Wiki source - https://github.com/libretro/Lakka/wiki/Playlists
Generated documentation - http://www.lakka.tv/doc/Playlists/

[Wilstorm]

That looks really sharp Herb! I like the layout and navigation. One thing that's kind of distracting is when you click a main section like 'MAME'. The page reloads and you have to scroll back down the MAME section again. Once you start selecting sub-sections it does stay static.

The other thing is the navigation bar looks old school or something to me. I can't quite put my finger on it. The pages are vibrant and lively but that side bar is "flat" but when gathering information and learning some sites are to flashy. I don't know.

Great job it looks really nice! Mark nice job on updating the ROMs section. I always thought a program is only as good as its documentation and RetroPie is definitely doing right! :)

[HerbFargus]

@markwkidd from what I gather lakka uses the bootswatch theme, I am looking more for a theme that has complete nav and dropdowns on the left side.

How I envision it is to have 3ish levels of navigation where I have one master config file that defines the TOC.

So it would be

• Top level togglable nav (Home, Emulators, Ports, Advanced Configs, Development, etc)
  
  
  
  • Second Level Nav (Individual Wiki Pages)
    
    
    
    
    
    • Third Level Nav (markdown headings for each wiki page #, ##, ###)
    
    
    
  
  

example config

pages:

Home
   - index.md
      - What is RetroPie
      - What is an Emulator
      - What are ROMS
      - Getting Started
Emulators
   - AGS
      - Roms
      - Controls
   - Amiga
      - Roms
      - Controls

etc.

Example from borg docs:

[HerbFargus]

I've updated my test repo to the material theme:

https://herbfargus.github.io/RetroPie-Docs/

I like that it has dropdowns and a page table of contents on the right. some of the wiki may need refactoring but I think this may be a good fit

I also may need to make some tweaks to the tables (the dark gray and blue don't work so well) and may change the header to a black or red and put in some page links to the forum, retropie home page, add a logo etc.

[joolswills]

Sorry I've not been involved here much - looked like everything was under control :) Just wanted to say that looks great - cheers!

[HerbFargus]

no worries @joolswills I know how you feel about docs anyways ;) will continue to tweak, may be some time before I am happy with it and as always happy to get feedback if its useful

[HerbFargus]

Just as an update I've made some good progress with this material theme:

https://herbfargus.github.io/docs/

It's pretty much about where I'd like it to be, there may be a few other tweaks (eg adding some navs to the forum and retropie home page perhaps)

Much of the wiki will need to be optimised so it translates properly on the conversion, and then once its more or less something that is ready for public consumption I'll migrate the repo to the RetroPie organisation and maybe look at pointing the dns to retropie.org.uk/docs or docs.retropie.org.uk. or whatever we deem most effective.

In case anyone is interested I wrote up some notes on it- they should be adaptable to pretty much any github wiki: https://github.com/HerbFargus/Raspberry-Pi-Scripts/wiki/Github-Wiki-to-Mkdocs

[HerbFargus]

Final product here:

https://retropie.org.uk/docs/

thanks to @joolswills for adding a module:

https://github.com/RetroPie/RetroPie-Setup/pull/1875

I wrote up a few notes on proper practises of editing the wiki so that it converts cleanly to the pretty wiki.

https://github.com/RetroPie/RetroPie-Docs/wiki/Editing-the-Wiki

There is a bug with single tables with the markdown parser so until a new release comes out it will need to be manually rolled back a version or patched locally.

more notes here: https://github.com/squidfunk/mkdocs-material/issues/143

Anyways now that this is completed this can be closed. I'll further tweak the wiki pages, and perhaps look at automation later if we deem it prudent.

[joolswills]

Thanks @HerbFargus !

[Anuskuss]

What about the automatic emoji conversion? For example Nintendo DS shows :small_red_triangle: instead of :small_red_triangle:

[HerbFargus]

Yes I need to kill those too. They arent supported icons in Python markdown. They aren't really all that useful in their current layout anyhow. If I were more ambitious I'd do a find and replace script for the admonition plugin. It that sounds like more work than I want to maintain at the current time

[dankcushions]

Looks great! Nice job!

I presume this auto-updates from the wiki? Is it a nightly thing?

[joolswills]

It's a manual process currently rather than nightly etc. (which has the benefit of allowing us to check the last wiki edits before generating etc).