> On 4. Oct 2017, at 09:57, Robert Munteanu <romb...@apache.org> wrote: > > On Tue, 2017-10-03 at 17:03 +0200, Konrad Windszus wrote: >>> On 3. Oct 2017, at 16:35, Bertrand Delacretaz <bdelacretaz@apache.o >>> rg> wrote: >>> >>> Hi, >>> >>> On Tue, Oct 3, 2017 at 3:50 PM, Konrad Windszus <konra...@gmx.de> >>> wrote: >>>> ...I think we also once discussed on the mailing list where to >>>> put bundle documentation: either in the readme or in the site >>>> itself... >>> >>> Now that we have complete control over the website we might >>> generate >>> http://sling.apache.org/documentation/bundles.html (or part of it) >>> using the GitHub API, or the module list that we use for Jenkins, >>> and >>> mostly use the module's README.md from now on. >> >> That sounds really good. >> @Robert: Would it be possible to maintain the module list as separate >> JSON file (currently contained in >> https://svn.apache.org/repos/asf/sling/trunk/tooling/jenkins/create_j >> obs.groovy). > > My plan is to access the repositories using the Sling API rather than > define a big list which can get out of date. I guess you mean GitHub API, right :-)? > > The 'canonical' way of doing this is by accessing https://api.github.co > m/orgs/${github_org}/repos and filtering based on the repo name. > >> >> Then we could easily use it for this purpose as well. >> The only question would be, when and how to trigger the update. >> >> Also we would have two different possibilities here: >> 1. Just link towards the readme.md (we must link to Github though, as >> Apache's Gitbox doesn't seem to be able to render the HTML from the >> MD, compare with https://gitbox.apache.org/repos/asf?p=nutch.git;a=bl >> ob;f=README.md;h=3aed205beb13d5b76c257d192d6c23d94669be35;hb=HEAD) >> 2. Generate the HTML page within the Sling site for each found >> readme. >> >> I would rather be in favour of option 2 though, as otherwise the >> readme link would only point towards Github, but of course then the >> updating issue is even more interesting... > > Option 2 sounds good to me as well. I am not sure though, as Bertrand > already mentioned, that we can rely on the README.md format rendering > 100% as expected in a different context.
I am pretty sure that there are slight differences on how the MD files is rendered with JBake 2.5.1 and with GitHub, so most probably some documentation will not work on either GitHub or Sling Site. > > What we could do is: > > - always keep the documentation in sling.apache.org > - add a deep link from the README.md to the specific documentation page > on sling.apache.org . > > Thanks, > > Robert
