RFD: leveraging GitHub's asciidoc rendering for our Documentation/

Hi there,

I've been looking more to GitHub lately and was wondering whether it is worth to leverage their automatic asciidoc rendering for our asciidoc files. I have put up a test tree at

https://github.com/gitigit/git/tree/githubtest

which has all the renaming (*.txt -> *.asciidoc) and Makefile and script changes, but is missing some include changes (because include breaks anyway, see below).

The simple renaming already gives a rendered display of blobs for simpler asciidoc files like release notes

https://github.com/gitigit/git/blob/githubtest/Documentation/RelNotes/1.7.7.asciidoc

and api documentation

https://github.com/gitigit/git/blob/githubtest/Documentation/technical/api-credentials.asciidoc

For the man pages, there are several problems as can be seen here:

https://github.com/gitigit/git/blob/githubtest/Documentation/git-blame.asciidoc

Our own customisation is not loaded (of course) so that, e.g., the linkgit macro does not work; and the include statement makes GitHub's parser unhappy and choke.

Does anybody feel this is worth pursuing?

+ Nicer blob view
+ Simpler way to judge documentation changes
- Need to get our asciidoc config in there
- GitHub's parser neeeds to learn include

Michael

Hey,

On Fri, Sep 9, 2011 at 7:34 AM, Michael J Gruber <git@drmicha.warpmail.net> wrote:

I can change this so we can render .asc if that's less ugly. I've been meaning to do this for a while, but I don't think I ever incorporated it.

If this is interesting to people, I can help out. However, you can also fix rendering issues, as long as they don't introduce security issues (which 'include' and macros can do) by fixing it here:

https://github.com/github/markup

That is the rendering engine we use. If you make it work how you want and it's safe and you send us a pull request, we'll happily take fixes to the asciidoc renderer.

Scott

On 09/09/2011 05:45 PM, Scott Chacon wrote:

What about letting the project set a gitattribute that tells github how to render particular files? It would not require files to be renamed, and it would be more flexible.

OTOH it would not be possible to apply gitattributes (or file renamings)
to old revisions, so the history would continue to be rendered naively.
 But here's an additional idea: github could provide web access to the
equivalent of $GIT_DIR/info/attributes (a project-wide .gitattributes
file), which would allow the rendering of files in historical revisions
to be customized and would also allow github rendering behavior to be
defined even in projects that do not want github-specific tags in the
.gitattributes files in their project.

Michael

Michael Haggerty venit, vidit, dixit 09.09.2011 17:58:

I don't think that the naming is a problem. In fact, we have .txt files which are asciidoc and some which are not, so renaming the former is an improvement in itself.

Also, I don't mean to replace our prerendered html. Just a nicer source view for documentation source.

Since this is about source view, we might not even want to execute an include - but we don't want the rendering to stop where there is one either.

Besides linkgit and things like apostrophe, all our asciidoc marcos are workarounds for docbook, and thus a non-issue for html rendering.

Don't know where the parser gets stuck. Maybe cwd is not where one thinks it is, and safe mode spoils the party.

Michael

Scott Chacon wrote:

Rather than forcing a rename on the repository, do you think it would be possible to implement some form of gitattribute support in GitHub? The user could then specify something like render=asciidoc (as opposed to, say, render=markdown or render=rdoc or whatever else you support): a few simple additions to .gitattributes and the user would be able to customize the cooked file view without needing to use GitHub's expected extension.

Michael J Gruber <git@drmicha.warpmail.net> writes:

Personally I am not very interested. Couldn't you just visit the html branch instead for viewing?

Junio C Hamano venit, vidit, dixit 09.09.2011 19:37:

For viewing what you generated yes, of course. Though there's some fiddling if you want to view a specific version. And even for the latest version it is more direct to click on the file in the tree and see it rendered.

But what I had in mind was being able to view anyone's branches like that, to aid review of a patch which is on list and in a branch on GitHub, say for restructuring layout or presentation of some man pages. The linkgit and include issues are a bit of a showstopper (looks like lots of digging in foreign code).

Michael

On Fri, Sep 09, 2011 at 10:37:24AM -0700, Junio C Hamano wrote:

I agree that it's not very nice for release-quality documentation. But if I understand correctly, Michael means that you can go straight to any blob at any commit of any fork on github, and get the rendered (or raw) version. Which is neat.

How frequently do you build the html branch? I always assumed it was once in a while (every push?), not for every commit.

We could help that along by giving our documentation a more descriptive filename. But it would be cool if GitHub respected gitattributes for this, too.

-Peff

Jeff King <peff@peff.net> writes:

I don't ;-)

Every time "master" is updated to the official distribution point, i.e., kernel.org (which currently is down). A post-update hook runs there, fetches the "master" branch commit into a separate repository, rebuilds the documentation, updates "html" and "man" branches and pushes the results back to that distribution point repository.

The mirrors will pick the result up after all that happens (or they may lag but they will eventually catch up).

forgot to copy the list; sorry...

---------- Forwarded message ----------
From: Sitaram Chamarty <sitaramc@gmail.com>
Date: Fri, Sep 9, 2011 at 9:24 PM
Subject: Re: RFD: leveraging GitHub's asciidoc rendering for our Documentation/
To: Michael J Gruber <git@drmicha.warpmail.net>

On Fri, Sep 9, 2011 at 8:04 PM, Michael J Gruber <git@drmicha.warpmail.net> wrote:

maybe github will consider supporting linkgit?  3 letters are common anyway :)

For a long time, I relied on github's rendering for all of my (gitolite) documentation.  Eventually I realised it is too slow to render.  More importantly, the whole github "presence" was extraneous to the manpage, and often distracted my readers.

Eventually I started pre-rendering my documentation to HTML myself and pushing it to a branch called "gh-pages".  Contrast the visual appeal of the github-rendered page [1] versus the pre-rendered page [2].  (I admit I do have some very minimal CSS in my version but that's another plus point for pre-rendering)

[1]: https://github.com/sitaramc/gitolite/blob/pu/README.mkd [2]: http://sitaramc.github.com/gitolite/README.html