Operation Make the Wiki Pretty!

herb_fargus

I've deployed the latest and can confirm the nested lists are working with the 4 spaces.

I wrote up quick workflow on deploying the docs (mostly for personal reference) likely can be improved

https://github.com/RetroPie/RetroPie-Docs/wiki/Updating-the-Docs

hooperre

Edit: Nvm. Thought it was live. Still looks great haha.

BuZz

@hooperre the wiki is now converted and available from the docs link at the top of the screen here. Herb did a great job. It's still being improved but the documentation is now more accessible than it was via GitHub.

backstander

@herb_fargus
I might have trouble explaining this but...

When you're trying to point someone to a selection on one of the Wiki pages, it uses the # sign + the name of that header (without any spaces/special characters and all in lowercase) like for example:
https://github.com/RetroPie/RetroPie-Setup/wiki/First-Installation#installation

For me to get that link I click on that "Installation" header and it gives me that address so I can post it for someone on the forum.

Now the Docs, that # sign thing works but I can't click on that "Installation" header to easily give me this address:
https://retropie.github.io/RetroPie-Docs/First-Installation/#installation

I don't know anything about mkdocs but is this something that can be added or is it not available like github has it?

herb_fargus

@backstander I believe that's specific to github. Isn't clicking on the TOC on the right the same thing though?

backstander

Isn't clicking on the TOC on the right the same thing though?

Yes, I didn't realize that was clickable ;-)
Thanks @herb_fargus

mrbwa1

Does anyone have an opinion ofn having the FAQ at the Top Level instead of under Troubleshooting. I have spent too many years in support and folks don't seem to look at Troubleshooting, but will look at an FAQ.

Not a big deal if it's current place is where it should be, just thinking out loud.

backstander

@mrbwa1
I agree. To me I think of FAQ and Troubleshooting as very closely related (if not the same thing) but non-technical users think of FAQ as something they will read and Troubleshooting as something that's way over their heads and they don't typically read.

herb_fargus

@mrbwa1 I put it down there because for one it's a bit outdated, and most people's frequently asked questions I would hope would be addressed on the first installation page, or at the very least individual system pages.

I'm also more of the opinion that people should take the time to understand how the system works rather than chasing Willy nilly through the infinite variations of questions that are derived from the same base misunderstanding.

The current FAQ just looks spammy to me. I don't know personally how I want it laid out or even what I want it to include. I'm probably going to remove at least a few of them as they are irrelevant. I'm almost more partial to a more generalised what is emulationstation what is retropie what are ROMs etc. Rather than the customised tweaks or questions about specific games...

Idk what do you think?

backstander

@herb_fargus

The current FAQ just looks spammy to me.

I agree but I don't know what could be done to make it flow better.

Idk what do you think?

I personally like the technical aspects of the wiki but when someone is new here they might want something a little more stripped down and the basics.

Maybe have a first page with the basics and a 2nd page with all the advanced features per system? Idk, I'm just thinking out loud.

detron

I think the retropie.org.uk/docs/ looks great. I may be the oddball here, but is there an "off-line" version of the manual?
I find that the times I do not have internet access are usually the times I would take a deeper look at manuals and configurations.

I know that online stays current, and some of the links go to other sites, but I was just curious.

thank you.

PS. I would buy a "RetroPie: The Complete Manual" type book. since I already buy things like

alt text

and

alt text

meleu

@detron said in Operation Make the Wiki Pretty!:

but is there an "off-line" version of the manual?

what about downloading the current version to your computer right now?

Here is the command to do the trick:

EDIT: removed the trick because it can stress the server.

detron

@meleu said in Operation Make the Wiki Pretty!:

@detron said in Operation Make the Wiki Pretty!:

but is there an "off-line" version of the manual?

what about downloading the current version on your computer right now?

Here is the command to do the trick:
wget \
    --recursive \
    --no-clobber \
    --page-requisites \
    --html-extension \
    --convert-links \
    --restrict-file-names=windows \
    --no-parent \
    --domains retropie.org.uk \
    https://retropie.org.uk/docs/
It may take a couple of minutes. After it ends you'll can see a directory named retropie.org.uk/. You can access the docs main page locally at retropie.org.uk/docs/index.html.

But, hey!, we are here for gaming but it's for learning too, right? Then here is the explanation of each option used on that command:

--recursive: follow links to create a local version of the remote web site.

--no-clobber: do not overwrite existing files (useful when you cancel the download and then execute that command again).

--page-requisites \: download all the files necessary to properly display a given HTML page (images, CSS, etc.).

--html-extension: save files with .html extension.

--convert-links: after the download is complete, convert the links in the document to make them suitable for local viewing.

--restrict-file-names=windows: modify filenames to make them work in Windows as well (useful if you plan to move the files to a Windows computer).

--no-parent: don't follow links outside the /docs directory.

--domains retropie.org.uk: don't follow links outside retropie.org.uk.

https://retropie.org.uk/docs: the URL of the website (or just a directory from that website) you want to download.

@meleu

thank you very much. I thought about doing this, but without permission, it seemed like theft.
I appreciate the explanation of each of the options, well done! others may find that useful too.

I have used wget just for files here and there, usually for sites I use HTTrack. usually just for reconnaissance for penetration tests . (I am a network security guy, but a white hat, I always get permission)

meleu

@detron if your concern is about stressing the server, you can also use the --wait option. For example --wait=2 to wait 2 seconds between each retrieval. ;-)

detron

@meleu said in Operation Make the Wiki Pretty!:

@detron if your concern is about stressing the server, you can also use the --wait option. For example --wait=2 to wait 2 seconds between each retrieval. ;-)

that sounds even better. I will do this on my next reboot (in Windows for school. CHFI uses .pdf files that REQUIRE Adobe Acrobat due to protections) really funny since most of the work done with CHFI is in Linux. Same problem when I did the Certified Ethical Hacker Certification.

herb_fargus

@detron I had considered using readthedocs as it has options for html/PDF/epub export along with versioning but I didn't want to go through the hassle of converting markdown to restructured text. It would have been prohibitive especially if we want the community to continue to contribute to the wiki. Markdown is much simpler.

The process for creating the static pages is relatively simple through some parsing. Basically we clone the GitHub wiki repo, parse the markdown to HTML and generate the static pages through makedocs with minor configs/css etc.

@BuZz actually created a useful module that can be run manually that will generate the docs locally.

Source here:

https://github.com/RetroPie/RetroPie-Setup/blob/master/scriptmodules/admin/wikidocs.sh

sudo ~/RetroPie-Setup/retropie_packages.sh wikidocs depends

sudo ~/RetroPie-Setup/retropie_packages.sh wikidocs sources

sudo ~/RetroPie-Setup/retropie_packages.sh wikidocs build

sudo ~/RetroPie-Setup/retropie_packages.sh wikidocs install

Should generate a folder of the static pages in ~/RetroPie-Setup/tmp/build/wikidocs I believe ( or something like that, don't have access to my pi to check

The upload function is what we use to push updates to our server but requires an ssh key, a server side script runs the builds automagically though so we don't have to push updates manually.

detron

@herb_fargus

thank you for explanation, and the wonderful work done on RetroPie, in all of its parts.

the fact that all replies to my inquiry were detailed really shows how wonderful this community is.

thank you everyone

meleu

@herb_fargus hey herb, I'm using what you did here to get some inspiration for another project documentation and I have a question: did you edited/created the mkdocs.yml from scratch by hand? (notably the pages: section).

herb_fargus

@meleu yes. But parts can be batch generated from the GitHub wiki list

meleu

@herb_fargus thanks, I noticed that and your work is being very helpful.

Are you OK if I use what you wrote for Editing the Wiki on my repo wiki too?

The documentation project I'm starting is RetroAchievements related.