Merge pull request #391 from github/add-ids-to-rsts

Add IDs to the headers generated by RST

lib/github/commands/rest2html

@@ -66,12 +66,15 @@ class GitHubHTMLTranslator(HTMLTranslator):
     # see also: http://bit.ly/1exfq2h (warning! sourceforge link.)
     def depart_document(self, node):
         HTMLTranslator.depart_document(self, node)
-        self.html_body.pop(0)
-        self.html_body.pop()
+        self.html_body.pop(0) # pop the starting <div> off
+        self.html_body.pop() # pop the ending </div> off
 
     # technique for visiting sections, without generating additional divs
     # see also: http://bit.ly/NHtyRx
+    # the a is to support ::contents with ::sectnums: http://git.io/N1yC
     def visit_section(self, node):
+        id_attribute = node.attributes['ids'][0]
+        self.body.append('<a name="%s"></a>\n' % id_attribute)
         self.section_level += 1
 
     def depart_section(self, node):

test/markups/README.rst.html

@@ -8,6 +8,7 @@ <h2>Subtitle</h2>
 <li><a href="#field-list">Field list</a></li>
 </ul>
 </div>
+<a name="header-2"></a>
 <h2><a href="#id1">Header 2</a></h2>
 <ol>
 <li>Blah blah <code>code</code> blah</li>
@@ -46,6 +47,7 @@ <h2><a href="#id1">Header 2</a></h2>
 <a href="https://scan.coverity.com/projects/621"><img alt="Coverity Scan Build Status" src="https://scan.coverity.com/projects/621/badge.svg">
 </a>
 <img alt="Coverity Scan Build Status" src="https://scan.coverity.com/projects/621/badge.svg">
+<a name="field-list"></a>
 <h2><a href="#id2">Field list</a></h2>
 <table frame="void" rules="none">
 

test/markups/README.rst.txt.html

@@ -1,5 +1,6 @@
 <h1>Header 1</h1>
 <p>Example text.</p>
+<a name="header-2"></a>
 <h2>Header 2</h2>
 <ol>
 <li>Blah blah <code>code</code> blah</li>

test/markups/README.toc.rst

@@ -0,0 +1,30 @@
+.. contents::
+    :backlinks: none
+
+.. sectnum::
+
+Introduction
+============
+
+What is pycparser?
+------------------
+
+**pycparser** is a parser for the C language, written in pure Python. It is a
+module designed to be easily integrated into applications that need to parse
+C source code.
+
+What is it good for?
+--------------------
+
+Anything that needs C code to be parsed. The following are some uses for
+**pycparser**, taken from real user reports:
+
+* C code obfuscator
+* Front-end for various specialized C compilers
+* Static code checker
+* Automatic unit-test discovery
+* Adding specialized extensions to the C language
+
+**pycparser** is unique in the sense that it's written in pure Python - a very
+high level language that's easy to experiment with and tweak. To people familiar
+with Lex and Yacc, **pycparser**'s code will be simple to understand.

test/markups/README.toc.rst.html

@@ -0,0 +1,32 @@
+<div>
+<p>Contents</p>
+<ul>
+<li>
+<a href="#introduction">1   Introduction</a><ul>
+<li><a href="#what-is-pycparser">1.1   What is pycparser?</a></li>
+<li><a href="#what-is-it-good-for">1.2   What is it good for?</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<a name="introduction"></a>
+<h2>1   Introduction</h2>
+<a name="what-is-pycparser"></a>
+<h3>1.1   What is pycparser?</h3>
+<p><strong>pycparser</strong> is a parser for the C language, written in pure Python. It is a
+module designed to be easily integrated into applications that need to parse
+C source code.</p>
+<a name="what-is-it-good-for"></a>
+<h3>1.2   What is it good for?</h3>
+<p>Anything that needs C code to be parsed. The following are some uses for
+<strong>pycparser</strong>, taken from real user reports:</p>
+<ul>
+<li>C code obfuscator</li>
+<li>Front-end for various specialized C compilers</li>
+<li>Static code checker</li>
+<li>Automatic unit-test discovery</li>
+<li>Adding specialized extensions to the C language</li>
+</ul>
+<p><strong>pycparser</strong> is unique in the sense that it's written in pure Python - a very
+high level language that's easy to experiment with and tweak. To people familiar
+with Lex and Yacc, <strong>pycparser</strong>'s code will be simple to understand.</p>