[jira] [Updated] (SAMZA-297) Allow linking to sub-headings in the documentation

["Martin Kleppmann (JIRA)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/SAMZA-297?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Martin Kleppmann updated SAMZA-297:
-----------------------------------

    Attachment: SAMZA-297.1.patch

Attaching patch for a Gemfile (which specifies the dependencies), Gemfile.lock (which locks down the versions of transitive dependencies) and corresponding README and config updates. RB: https://reviews.apache.org/r/22748/

A minor issue is that Gemfile.lock is autogenerated, and I'm not sure whether we can add an ASF header to it (you're not supposed to edit the file manually). Would that be a problem?

> Allow linking to sub-headings in the documentation
> --------------------------------------------------
>
>                 Key: SAMZA-297
>                 URL: https://issues.apache.org/jira/browse/SAMZA-297
>             Project: Samza
>          Issue Type: Improvement
>            Reporter: Martin Kleppmann
>            Assignee: Martin Kleppmann
>         Attachments: SAMZA-297.1.patch
>
>
> Some of the documentation pages are quite long, so for cross-references in the docs, it's useful to be able to link to sub-headings within a page. Jekyll/Redcarpet supports this with the "with_toc_data" option, which we have enabled.
> However, different versions of the Redcarpet gem treat that option differently. The latest version generates an ID based on the text of the heading, for example:
> {noformat}
> <h4 id="log4j-configuration">Log4j configuration</h4>
> {noformat}
> whereas older versions generate an ID which is numbered sequentially within the page:
> {noformat}
> <h4 id="toc_0">Log4j configuration</h4>
> {noformat}
> The new behaviour is probably preferable, as it's less susceptible to being broken if documentation sections are added or reordered. However, this means that we have to ensure that all committers who build the website are using the latest version of the gems.
> The standard way of enforcing version constraints and dependencies for Ruby gems is [Bundler|http://bundler.io/]. I propose adding a bundler Gemfile to the docs directory, which would make that pretty easy.



--
This message was sent by Atlassian JIRA
(v6.2#6252)