[
https://issues.apache.org/jira/browse/SLING-7176?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16191084#comment-16191084
]
Robert Munteanu commented on SLING-7176:
----------------------------------------
I've been thinking about an idea of scripting README generation. I think
[~olli] did the same for this major README overhaul that just took place.
The idea would be to have all information specific to a module moved out the
README.md file and then used a script to pick up variables and move them there.
We can either store the information in the pom.xml or in a sling-specific file
( for instance .sling or a .sling/ directory ).
I think we currently have the following specific needs:
* bundle name - extracted from the pom.xml
* bundle documentation link - can be added to the pom.xml or to a different file
* README specific additions ( for instance
[launchpad/testing|https://svn.apache.org/repos/asf/sling/trunk/launchpad/testing/README.md]
has information on executing individual tests ) - this one is better saved
under a {{.sling/readme-fragment.md}} file fragment which gets appended to the
final README.md
We might have more scenarios but I'm inclined to propose having an optional
{{.sling}} directory added to each module which is a source of structured
information used for automation. We can also use it to store additional data
that is needed for the CI build - what to archive, supported jdks, etc . I am
suggesting a directory and not a file since we might need to add free-form text
which gets a bit awkward in a JSON file.
> Link and embed bundle readme's from Sling Site
> ----------------------------------------------
>
> Key: SLING-7176
> URL: https://issues.apache.org/jira/browse/SLING-7176
> Project: Sling
> Issue Type: Improvement
> Components: Site
> Reporter: Konrad Windszus
>
> As proposed in
> https://lists.apache.org/thread.html/7cb85c44d3b852fd13acc66413606d1ada1e6585eda2220981ad0c6d@%3Cdev.sling.apache.org%3E
> we should link
> # from the bundle's readme MD files to the according page below
> http://sling.apache.org/documentation/bundles.html
> # from the [bundles overview
> page|http://sling.apache.org/documentation/bundles.html] in the Sling Site
> towards the individual bundle's readmes
> The latter should be done automatically by leveraging JBake template
> functionionality.
> Some technical hints on how to implement this:
> # Come up with a new JBake template: bundles
> # This template will use the Github API with its [List organization
> repositories
> method|https://developer.github.com/v3/repos/#list-organization-repositories]
> to figure out all Sling repositories
> # For all repositories containing a readme.md file a link towards this file
> (on Github) should be placed in the bundle overview page
> # To figure out the relation between individual Sling Site Bundle
> Documentation pages (e.g.
> http://sling.apache.org/documentation/bundles/models.html) and the according
> readme.md, the readme should be optionally extended with a link towards the
> Sling Site page.
> # TBD: format of the link towards the Sling Site documentation, so that it
> can be easily extracted with Groovy to put the link to the readme in the
> right position of the bundle overview page.
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
