Commits

Anonymous committed 32559a0 Merge

Merge

  • Participants
  • Parent commits 62c045a, c7f02ae

Comments (0)

Files changed (5)

 
     1. Get it:
         hg clone http://bitbucket.org/khorn/lore2sphinx
+
     2. Install with 'python setup.py install'
     
     3. Copy 'lore2sphinx.conf.default' to 'lore2sphinx.conf'
     
     5. Run bin/lore2sphinx. This will generate the rst files for Sphinx.
         - If the script can't find your lore2sphinx.conf file, use the '-c' option
-          to specify the config file's exact location
+          to specify the config file's exact location. Specify the '--help' command
+          to see all available options.
     
     6. Build the Sphinx project:
-        cd profiles/twisted/source
+        cd profiles/twisted
         make html
     
     7. Look at the output in build/html/ to see what's broken
     
-    8. Give feedback!
+    8. Give feedback! Open a ticket on Bitbucket or use the Twisted-Python mailinglist.

lore2sphinx.conf.default

 #
 # Also note that directories may be specified either with or without 
 # trailing backslashes.
+
 [twisted]
 
 # The 'lore_dir' setting is the directory where the lore source documents
-# to be converted exist.
+# to be converted exist, like /path/to/twisted/trunk/doc
 lore_dir = C:\Documents and Settings\hornk\Desktop\twisted-dev\doc\
 
 # The 'output_dir' setting is the directory to which Sphinx/ReST files

lore2sphinx/__init__.py

 from string import whitespace
 from pprint import pformat #, pprint
 
+# for experiment using regexes to clean up rst artifacts
+import re
+
 import urllib
 import urlparse
 
 NL = '\n'       # New Line
 BL = '\n\n'     # Blank Line
 SPACE = ' '     # a space character
+ESCAPED_SPACE = r'\ '   # a rst 'escaped space'
 
 #~ LIST_TAGS = ['ol', 'ul', 'dl']
 LIST_TAGS = ['ol', 'ul']
 # lore2sphinx version nr
 __version__ = version = '0.1'
 
+# set up experimental regexes?
+
+# replace double-backticks without a preceding space
+#~ dbl_backticks_no_prespace = re.compile('(?<=[^\s])(``)')
+#~ dbl_backticks_no_prespace = re.compile('(?<=[^\s])(``.*``)')
+
+#~ dbl_backticks_no_prespace = re.compile('(?<=[^\s])(``[^`]*``)')
+#~ role_no_prespace = re.compile('(?<=\w)(:\w+:)')
+#~ spaces_before_punctuation =re.compile('(?<=`) ([.,?!])')
+#~ links_no_prespace
+
 def underline(strng, char):
     '''underline a string'''
     strng = strng.strip()
     def toc_indent(self, a_string):
         return (' ' * self.toc_spaces) + a_string
 
-    #~ def format_toc(self):
-        #~ '''build the rst toctree block'''
-        #~ if not self.source_filepath.endswith('index.xhtml'):
-            #~ return ''
 
-        #~ # get sibling files
-        #~ sibs = get_sibling_files(self.source_filepath)
-        #~ sib_docs = [os.path.splitext(f)[0] for f in sibs
-                        #~ if f.endswith('.xhtml')]
-
-        #~ # get subindexes
-        #~ subindexes = get_subindexes(self.source_filepath)
-        #~ toc_entries = sib_docs + subindexes
-        #~ toc_fmt_entries = ['   ' + e for e in toc_entries]
-        #~ if toc_fmt_entries:
-            #~ toc_header = [''.join(('.. toctree::', NL, '   :maxdepth: 2', NL))]
-            #~ return NL.join(toc_header + toc_fmt_entries + [NL])
-        #~ else:
-            #~ return ''
+    ################################################
+    # TOC and Footnote formatting
+    #   (happens outside the handle_element() flow)
             
     def format_toc(self):
         '''build the rst toctree block - from links in the document''' 
-        # only put tocs in index.httml files
+        # only put tocs in index.html files
         if not self.source_filepath.endswith('index.xhtml'):
             return ''
             
 
         return ''
 
+
+    #########################
+    # Main processing methods
+
     def pre_process(self):
         self.txt_out += self.prelude
 
 
         # TODO: output footnote contents
         self.txt_out += self.format_footnotes()
+        
+        # use a couple of regexes to clean up a little
+        # WARNING! EXPERIMENTAL!
+        # better to try getparent() or getprevious() in the parsing
+        
+        # TODO: this one is broken, need to only put spaces in front of 
+        #       _first_ set of backticks
+        #~ self.txt_out = dbl_backticks_no_prespace.sub(
+                            #~ lambda m: ' %s' % m.group(1), self.txt_out)
+        #~ self.txt_out = role_no_prespace.sub(
+                            #~ lambda m: ' %s' % m.group(1), self.txt_out)
+        #~ self.txt_out = spaces_before_punctuation.sub(
+                            #~ lambda m: '\ %s' % m.group(1), self.txt_out)
+        # TODO: need something to fix links without preceding spaces
 
     def handle_element(self, elem):
         '''
         except:
             prepare_func = self.prepare_default
         finally:
+        # ACK! TODO: no prepare_X methods currently return any output, but 
+        # if any ever do, this will break horribly!
             txt_out = prepare_func(elem)
 
         # handle children
 
         return txt_out
 
-    def prepare_default(self, elem):
-        '''
-        By default, do nothing.
-        '''
-        pass
+
+    ##################
+    # Comment handler
+    #   handled separately since it's different from standard Elements
 
     def format_comment(self, elem):
         if '\n' in elem.text:
             return ''.join((BL, comment_line, BL))
         #~ return ''.join((BL, '.. ', indent_block(elem.text, 3), BL))
 
+
+    ################################
+    # Default and pass-thru handlers
+
+    def prepare_default(self, elem):
+        '''
+        By default, do nothing.
+        '''
+        pass
+
     def format_default(self, elem, contents):
         '''
         default element handler.
     format_head = format_pass
     format_h1 = format_pass
 
+
+    #######################################
+    # HEAD contents and header tag handlers
+
     def format_link(self, elem, contents):
         '''Format a <link> tag.'''
         rel = elem.attrib.get('rel', None)
             author_name = elem.attrib.get('title', None)
             author = ':Author: %s' % (author_name)
             return ''.join((BL, author, BL))
-
-    #~ def format_basic(self, elem):
-        #~ return n2es(elem.text)
+        #else
+        return ''
 
     def format_title(self, elem, contents):
         '''Format the <title> element.
         uline_text = underline(remove_newlines(title_text), '~')
         return ''.join((BL, uline_text, NL, n2es(elem.tail)))
 
+    def format_h4(self, elem, contents):
+        '''Format a <h4> tag.
+        
+        ..note:: The Lore "specification" does not address h4 tags, 
+                 but Lore itself supports it and h4 tags are used by 
+                 some Lore users, so we support it.
+        '''
+        title_text = ''.join((n2es(elem.text), contents)).strip()
+        uline_text = underline(remove_newlines(title_text), '^')
+        return ''.join((BL, uline_text, NL, n2es(elem.tail)))
+
     def format_br(self, elem, contents):
         '''Format a <br> tag.'''
         return NL + n2es(elem.tail)
         return '' + n2es(elem.tail)
 
 
+    ########################
+    # Inline markup handlers
+
     # NOTE: inline elements may not be nested and may not start or end
     # with whitespace, ref: http://sphinx.pocoo.org/rest.html
-    # TODO: these should throw warnings if they have nested markup
+    # TODO: maybe these should throw warnings if they have nested markup?
 
     def format_q(self, elem, contents):
         '''Format a <q> tag.'''
         '''
         process the file.
         '''
+        # TODO: refactor...
+        #   dprocessor should probably be created in __init__
         self.dprocessor = DocumentProcessor(self.config,
                                             self.source_filepath,
                                             self.dest_filepath)

profiles/twisted/source/conf.py

 
 # General information about the project.
 project = u'Twisted'
-copyright = u'2001-2010, Twisted Matrix Labs'
+copyright = u'2001-2011, Twisted Matrix Labs'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # Base url for apilinks extension
 apilinks_base_url = 'http://twistedmatrix.com/documents/current/api/'
 traclinks_base_url = 'http://twistedmatrix.com/trac'
+
+# A list of regular expressions that match URIs that should
+# not be checked when doing a 'make linkcheck' build (since Sphinx 1.1)
+linkcheck_ignore = [r'http://localhost:\d+/']
         'Operating System :: OS Independent',
         'Framework :: Twisted',
         'Programming Language :: Python',
-        'Programming Language :: Python :: 2.5',
         'Programming Language :: Python :: 2.6',
+        'Programming Language :: Python :: 2.7',
         'Topic :: Software Development :: Libraries :: Python Modules',
     ]
 )