Wiki for luapower?


  • Hi,

    Have you considered a wiki for luapower? I would be more than happy to contribute to docs, tutorials, etc. as I am sure other users would as well.

    It also takes that burden of off you a bit. Anyway, just a suggestion.

    Cheers,


  • wiki 1 developing 1 docs 1 help 2
    11
    Posts
    3324
    Views
    Log in to reply


  • That's a great idea. Should we use github wikis for that? Or this forum?

    I was also thinking of making the documentation pages editable on the website directly. Would that be a good idea? They're written in pandoc markdown after all. The downside is that all the commits will be done in my name (unless I add github logins to the website which I suspect is a lot of work).

    Right now the only way to edit the docs is to fork the module, edit the doc offline and then send a pull request to the origin. This is way too much work when all you want is to fix a typo.



  • The only thing I don't like about GitHub wikis is you can't do much with page/topic/toc arrangement, which I think is important.

    Does the forum have wiki support? The closer, the better.

    Cheers.



  • It doesn't explicitly, but it does have categories, you can edit posts anytime and you can make them in markdown. So technically there's not much difference between a forum post and a wiki page, except it's still called a "topic". I can understand wanting to have a separate place for wiki though. Hm...



  • I've used https://readthedocs.org/ before, you can actually self-host the app, but the accounts are free, so it may not be worth the hassle.

    The other one I have used is mkdocs, for markdown, but I'm not sure how "community" oriented that one is as far as editing pages, etc.

    Readthedocs is basically a "documentation" wiki.

    Cheers.



  • Wait, these are wikis? They look like doc generators.



  • Hi,

    It's kind of a hybrid of wiki and docs. It does generate the docs from your repo, but not from your source, you write in markdown and can add a config to customize some of it. I've got one running here for a Luapower package I am almost done with. http://luapower-unqlite.readthedocs.org/ (work in progress).

    It's just an option, it also hooks directly to your repo pushes. If you add a link to your repo, you can have others edit it as well via GitHub. A straight wiki would be nice though. Just throwing out suggestions.

    Cheers.



  • Ok let's see if I got this right.

    We have two types of docs that we want to wikify here:

    • general docs about using luapower
    • module docs

    Let's clarify how it currently works and see what we want different:

    Currently both types of docs are written in markdown (all pandoc extensions also being supported -- eg. tables are heavily used to render the quick ref. API tables that you see on many modules). The general docs are here. The module docs are in each module's repo (called foo.md but you can also have "sub-docs" like foo_xxx.md or foo/xxx.md -- they will all be rendered no matter where they are, eg. see winapi).

    To edit the docs right now you have to click on the red github link at the top of the page and go edit the docs on github, just like with editthedocs. But we can do one better, and make an "edit on github" link that would go directly to the github editor for that particular doc. And yes, if it's not your repo github will make a fork etc.etc. so it's still not as easy as a direct "edit" button, but we could add that too. And if we add a "create new page" button too, I think we have a wiki :) Am I on the right track with this? Is that what we're missing or is there something else?



  • I didn't know about unqlite until know. Looks slick at less than 500k binary. Your binding looks pretty lightweight too. Out of curiosity, what does unqlite have over sqlite?

    [Note that LP packages are cloned into the same directory so if two packages both have mkdocs.yml they would conflict; same goes for README.md and the docs folder (the docs folder could be renamed unqlite or the docs could be moved to unqlite_about.md etc, but IMHO a single unqlite.md would look best).]



  • Update; I added an "Edit on Github" button on the bottom of all doc pages. It's not much but a step closer to the wiki.



  • Hi,

    Thanks for explaining the doc process. I'm still learning all the little details, and will rethink this a bit as well.

    Unqlite is more similar to Redis -- as a key/data store. Though much lighter in functionality. UnQLite can also emulate most MongoDB like functionality with its built in "Jx9" (basically JSON) internal scripting language. That is the part I'm trying to get working now, but having some trouble with a pointer error. So right now I only have the key store binded, with the transactions working as well. It's a continuation of a binding someone else started.

    SQlite is more similar to mySQL - SQL based. I still want to work on a SQLite package, but UnQLite ended up being a better option for me to learn FFI with.

    I've never touched C until luapower, and I've always wanted to learn more about FFI. You have succeeded at both, and now my mind is going crazy with ideas. Thanks for that. :p

    "Edit on Github" button is a good idea. I'll run through the process. I really enjoy documenting and distilling down ideas and workflows. My philosophy is "People are not programmers", so simple documentation allows your project to relate to more people and gain more traction, as most are just hacking about anyway, in my experience.

    Cheers.


wiki 1 developing 1 docs 1 help 2
11
Posts
3324
Views
Log in to reply

Internal error.

Oops! Looks like something went wrong!