Move documentation from RMOD to GitHub

[theseion]

@seandenigris Maybe you'd like to help ;)

[seandenigris]

What do you have in mind? GH wiki, pages, Pillar, something else?

[theseion]

Not sure yet. Have you ever worked with non-trivial documentation on GitHub? Any experience you can share?

I like documentation in the README but only for scanning it. So rather something like wiki. However, the GH wiki seems underwhelming to me, e.g. search is non-existent (why would I want to search for the name of a page? What I want is to search the contents of the wiki...). So maybe pages? Can we easily get good search on those? How would Pillar play into it? Would we simply generate HTML? I've never really worked with Pillar.

I'm happy to follow your lead, if you have any ideas.

[seandenigris]

I don’t have much experience in this area. Googling revealed that there is a Jekyll search plugin, but it seems to be unmaintained. Working in-(Smalltalk)-image would probably be the most flexible because we can export to several common formats, including HTML and markdown, a subset of which GToolkit supports as of a few days ago and Pharo will support in v10. IIUC pages can consume Markdown, injecting it into HTML templates. We could also potentially auto generate a readme that way. Maybe a TOC linked to the wiki?

For me, the best option at the moment is to work in GT because the markdown is live rendered, although maybe in Pharo support is usable if not “finished”. I don’t think there is a best practice here so probably do TSTTCPW and quickly error correct as needed

[theseion]

You are probably right that GT might be the simplest way aside from just publishing via GitHub pages directly. I tried that quickly and it works but it lacks search and there aren't a lot of options for styling etc. So I started looking around at how others publish documentation and came across Hugo. It's also a static site generator but has a ton of options while at the same time seems to be somewhat simple to set up. There are also a couple of nice themes. I like this one for example: https://themes.gohugo.io/hugo-book/. Hugo also seems to make it easy to integrate search and to build the site using GitHub Actions.

That sounds like something fun I'd like to play around with. I've published two markdown files under /docs for testing (the content isn't markdown yet, I simply copied the text from the current documentation).

If you're up for it, go ahead and try something. I'll give you permissions on the repository (just use a separate branch for now and commit with [skip ci].

[theseion]

I have an experimental setup with Hugo. It doesn't quite work like I want to yet but I have an idea how to do it. I've also added quick copies of all the documentation pages. Once we're done with the setup, we'll need to go through those in more detail.

There are two more things that I want to have in for the documentation:

1. documentation for each (active) version and the ability to get there easily
2. a changelog (I've ported the old changelog entries for a start)

If you want to play around with the docs and view them in your browser locally you'll need to install Hugo and run the server (hugo server --minify -s docs/hugo). It will hot reload any changes.

[theseion]

Here it is: https://theseion.github.io/Fuel/. The docs will build automatically when you push to master and include [docs] in the commit message. [docs] will also skip builds on Travis and Appveyor.

The configuration for Hugo is in the hugo directory on the master branch, the static pages are published to the docs branch.

You can run Hugo locally in the root directory by first fetching the theme submodule with git submodule update --init and then running Hugo with hugo server --minify -s hugo.

[seandenigris]

The search box seems to be doing something (typing there leads to fewer pages listed on the left), but doesn't exactly seem right. E.g. I typed "rename" and then clicked on "Builtin Header Support", which remained in the list. But it didn't seem to contain "rename"

[theseion]

I think that's because the search does fuzzy matching. It's neat but I agree, it could be better. Switching to a different theme or using a different search engine shouldn't be too difficult. But we'll focus on that when we're done with the rest (at least I am :) ).

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will remain open but will probably not come into focus. If you still think this should receive some attention, leave a comment. Thank you for your contributions.

[theseion]

Not stale.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will remain open but will probably not come into focus. If you still think this should receive some attention, leave a comment. Thank you for your contributions.