Switch the wiki platform

morganey-lang / Morganey

Lambda Calculus based, interpreted programming language that recognizes Church encoded structures.

43 stars 4 forks source link

Switch the wiki platform #107

Open rexim opened 8 years ago

rexim commented 8 years ago

Final Decision

Local doc/ folder in the src code repo

Scope

Take *.md's from wiki and put them to the doc/ folder in the source code repo preserving the history. git subtree and stuff.

I don't like that GitHub's wiki is disconnected from the issue tracker (I cannot close issues from commit message to wiki repo). Let's search for alternatives. For example, https://readthedocs.org/ But I'm not sure if ReadTheDocs is a good place for Wiki stuff.

@ForNeVeR @keddelzz what do you guys think?

ForNeVeR commented 8 years ago

I have been using it for another community project - Naggum. It looks nice, but requires configuration in python. Check the config, it's pretty big. I'd prefer some solution with lesser configuration required (and I'd even switch Naggum to it).

keddelzz commented 8 years ago

Maybe the simplest solution is to use Morganeys repo itself. There could be a docs/ or wiki/ folder where all wiki-related resources and and the wiki is located. The wiki could be written in Markdown or Org-Mode, and be "build" to pdf and html using pandoc or displayed by Github.

Edit: That would be similar to the idea to use ReadTheDocs, though. But with pandoc the style could be specified via css.

ForNeVeR commented 8 years ago

Well, ReadTheDocs supports custom themes too. It uses some sort of Python standard tool Sphinx to build the docs. And yeah, the pages will be stored in the repo, too.

I am not sure what should we do here. Maybe take a look at scaladoc?

ForNeVeR commented 8 years ago

Probably the simplest approach would be to just put the *.md docs to the doc/ directory. They will be part of main Morganey repo, and guys could then send patches to them using standard GitHub UI.

rexim commented 8 years ago

I think I like the idea with doc/ in the repo:

Docs are connected with issue tracker:
- I can close issues with commits related to the docs
- I can refer to exact revision of a doc page
Docs are available offline!
We can do custom generation:
- Our own styles
- Our own features:
- Issue number autodetection and generation corresponding link (yes, GitHub wiki doesn't support this simple vital shit!)
- Any other autodetection of anything else

Ok, I guess we agreed on local doc/ folder then. The scope of this issue will be pretty small. Just take *.md's from wiki and put them to the doc/ folder in the source code repo preserving the history. git subtree and stuff. I'm gonna do all of that.

Thank you guys for the comments!

rexim commented 8 years ago

This can be useful https://github.com/blog/2228-simpler-github-pages-publishing

ForNeVeR commented 8 years ago

Here's the workflow I've "invented" for Jabber-Net:

Place markdown doc sources and templates for doc generator into the project docs/ directory.
Create a simple script that will run generator and copy its output (plain HTML) into some directory.
Sometimes (e.g. for every release or after every significant change) rerun the script and publish its output into a special orphan branch created specifically for GitHub pages.

The result is here: https://fornever.github.io/Jabber-Net/

Orphan branch can be created by git checkout --orphan branchname.