I'm also adding other features we should have for Red docs: - search field: a true local search engine, not a wrapper on Google search. - versioning: ability for users to consult any previous version of the docs. - a simple way to track changes in the docs.
DocKimbel
For now, I would just link the docs from red-lang.org and host them on static.red-lang.org which points to my own server.
In a few months, when bootstrapped Red will be complete, I would like to move all to a new, more appealing web site. I might use a github repo for managing the static parts of the web site. I would also move the blog to WordPress or anything else than Blogger.
DocKimbel
About Git, it is not that complicated, you just need to learn a few (2-3) usage patterns to be able to install/update your local repo and submit a change. Maybe someone could provide a simple Red-repo-oriented tutorial using TortoiseGit and command-lines for those basic usage patterns?
AdrianS
GitHub Pages also serves up static html/css/js. Still, if you couldn't use any server-side scripting, you'd need to pre-generate the html and I guess you wouldn't want to do that.
DocKimbel
Pre-generated HTML: I certainly do want that. I have already a static server, so I don't need GitHub Pages so far.
- No need to expand or collapse the TOC on the left. You can see two top-level headings. - Single scrolling page you can scan. And I do like the visible scrolling in this case. - Summary doc string visible for each item. Again, good for scanning. - Having the number of examples listed is nice, and shows what needs examples. - It's a clean, effective layout to my eye, providing useful detail before drilling down.
Having the doc string there has the benefit of letting you use Find on a web page to help locate what you want by purpose rather than name. Having an a.k.a. (Also Known As) annotation could help too. I did this for myself when starting with REBOL, noting what equivalent funcs were in the environment I was coming from.
Gregg
While I can't commit to being the doc lead, if someone creates templates for output formats, and we have data in REBOL format to populate them with, I will commit, happily, to building doc generation tools.
Gregg: documenting the API (the Red words) is the easy part. The content could (should?) be extracted from the docstrings in boot.red (I haven't add any so far, contributions are welcome).
The level of info displayed by the clojuredocs quickref is fine to me, I have used similar approach in the past for documenting the RSP API:
Oldes, really nice popups with copy paste. Much better. Hard to believe you need a cheatsheet off-course ;-)
Arnold
So the Red docs are not makedoc(2) specific. You only want to be sure that they are in a format that can be handled using scripts like makedoc123 and generate all kinds of documenttypes, like webpages, pdf, (epub?) etc. If I understand correct.
DocKimbel
Makedoc would be the source format for the docs, the users would consume it in one of the exported formats available.
Gregg
Looking more at sencha/ext-js and closuredocs, I like aspects of both. Sencha has some very nice detail pages, and closuredocs has a clean feel, with easy ways to add examples, see also entries, and comments.
Gregg
Now I have to re-learn fetching the upstream master to my fork...
Andreas
Gregg: unless you actually want to push changes to your fork on Github, there's usually no need to maintain a "fork" on Github.
If you meant how to get the latest changes from Nenad's master into your local repository, that could/should be as easy as `git pull`.
(Depending on where you originally "cloned" from.)
Gregg
I'm trying the github Windows client, which should sync, but only have my fork in it right now. I thought the target workflow (in general) was to fork, push to that, then submit a pull request. My problem is spending little time on it, then letting it sit idle while it leaks out of my brain.
Andreas
Yeah, fork + push to fork + pull request is one typical contribution workflow.
However, if you just want to follow along with the updates, then you don't need your own fork and can just sync a local clone of Nenad's repository.