From 299e0d735bf9f1b1c68c713ec9142a300d3f00df Mon Sep 17 00:00:00 2001 From: Max Hurl Date: Thu, 13 Sep 2012 14:50:23 +0100 Subject: [PATCH] First draft of improved config based markdown converter --- docs-settings.yaml | 42 ++++++++++ docs/template.html | 10 ++- mkdocs.py | 185 ++++++++++++++++++++++++++++++++++++--------- 3 files changed, 199 insertions(+), 38 deletions(-) create mode 100644 docs-settings.yaml diff --git a/docs-settings.yaml b/docs-settings.yaml new file mode 100644 index 000000000..f76a30836 --- /dev/null +++ b/docs-settings.yaml @@ -0,0 +1,42 @@ +# Documentation settings for django rest framework +language: python + +docs_dir: docs +html_dir: docs/html + +base_url: http://tomchristie.github.com/django-rest-framework + +project_title: Django REST framework + +index_file: index.md + +version_number: 2.0.0 + +static_dirs: + - source: docs/static/css + target: css + - source: docs/static/js + target: js + - source: docs/static/img + target: img + + +#navigation and files +nav: + - section: + title: Home + file: index.md + - section: + title: Tutorial + pages: + - file: tutorial/1-serialization.md + title: 1 - Serialization + - file: tutorial/2-requests-and-responses.md + title: 2 - Requests and responses + - section: + title: API Guide + pages: + - file: api-guide/requests.md + title: Requests + - file: api-guide/responses.md + title: Responses \ No newline at end of file diff --git a/docs/template.html b/docs/template.html index f20aabac7..27b5d7d43 100644 --- a/docs/template.html +++ b/docs/template.html @@ -1,7 +1,7 @@ - Django REST framework + {{ project_title }} @@ -18,6 +18,8 @@ + {{ navigation }} +
@@ -26,7 +28,7 @@ - Django REST framework + {{ project_title }}
  • Home
    • @@ -74,10 +76,10 @@
diff --git a/mkdocs.py b/mkdocs.py index e04cfe0e9..b0574188a 100755 --- a/mkdocs.py +++ b/mkdocs.py @@ -1,45 +1,127 @@ #!/usr/bin/env python + +#### Requirements +# +# Markdown and Yaml installed +# pip install markdown +# pip install PyYAML +# +# +# A YAML config file created +# +# +# + +#### terminal usage +# python mkdocs.py [options] +# options: +# -c --configfile "Config file" + + import markdown import os import re import shutil import sys - -root_dir = os.path.dirname(__file__) -docs_dir = os.path.join(root_dir, 'docs') -html_dir = os.path.join(root_dir, 'html') - -local = not '--deploy' in sys.argv - -if local: - base_url = 'file://%s/' % os.path.normpath(os.path.join(os.getcwd(), html_dir)) - suffix = '.html' - index = 'index.html' -else: - base_url = 'http://tomchristie.github.com/django-rest-framework' - suffix = '' - index = '' +from optparse import OptionParser +import yaml -main_header = '
  • {{ title }}
    • ' -sub_header = '
  • {{ title }}
    • ' -code_label = r'\1' +parser = OptionParser() +parser.add_option("-c", "--configfile", type="string", action="store", dest="conf_file_path", help="Config File Path (YAML format)") -page = open(os.path.join(docs_dir, 'template.html'), 'r').read() +(options, args) = parser.parse_args() -# Copy static files -for static in ['css', 'js', 'img']: - source = os.path.join(docs_dir, 'static', static) - target = os.path.join(html_dir, static) - if os.path.exists(target): - shutil.rmtree(target) - shutil.copytree(source, target) +def create_files(conf_file_path): + # read the conf file + with open(conf_file_path, 'r') as f: + conf = yaml.load(f) -for (dirpath, dirnames, filenames) in os.walk(docs_dir): - for filename in filenames: - if not filename.endswith('.md'): - continue + root_dir = os.path.dirname(__file__) + docs_dir = os.path.join(root_dir, conf['docs_dir']) # where it gets the MD files from + html_dir = os.path.join(root_dir, conf['html_dir']) # where it puts 'em' + + #get the title + project_title = conf['project_title'] + + # is this a local build? + local = not '--deploy' in sys.argv # If not --deploy all links end with .html and base links contain file + + if local: + base_url = 'file://%s/' % os.path.normpath(os.path.join(os.getcwd(), html_dir)) + suffix = '.html' + index = 'index.html' + else: + base_url = conf['base_url'] # if for deployment use actual docs URL.. maybe make all relative later + suffix = '' # .html only needed for local + index = '' + + main_header = '
  • {{ title }}
    • ' + sub_header = '
  • {{ title }}
    • ' + code_label = r'\1' + + new_page = open(os.path.join(docs_dir, 'template.html'), 'r').read() + + # copy static + for static in conf['static_dirs']: + source = os.path.join(root_dir, static['source']) + target = os.path.join(html_dir, static['target']) + if os.path.exists(target): + shutil.rmtree(target) + shutil.copytree(source, target) + + # ======================================================================================================================== + + # create the naivgation based on the YAML settings + navigation = "
      {{ content }}
    " + + nav_content = "" + + for section in conf['nav']: + + # does this section have sub pages? + if 'pages' not in section: + # output non drop down nav + top_nav = "
  • " + section['title'] + "
    • " + else: + # output drop down nav + top_nav = "
  • " + section['title'] + "
      {{ drop_down }}
    • " + + drop_down = "" + for page in section['pages']: + inner_nav = "
  • " + page['title'] + "
    • " + drop_down += inner_nav + top_nav = top_nav.replace("{{ drop_down }}", drop_down) + + nav_content += top_nav + + navigation = navigation.replace("{{ content }}", nav_content) + + # ======================================================================================================================== + + # loop through all MD files + #for (dirpath, dirnames, filenames) in os.walk(docs_dir): # go through everything + + # for filename in filenames: + # if not filename.endswith('.md'): # ignore non md files + # continue + + def convert_file(filepath): + # build the tabe of contents + + # ======================================================================================================================== + + if not os.path.dirname(filepath): + #print 'is file' + dirpath = docs_dir + else: + #print os.path.dirname(filepath) + dirpath = os.path.join(docs_dir, os.path.dirname(filepath)) + + filename = os.path.basename(filepath) + + # ======================================================================================================================== toc = '' text = open(os.path.join(dirpath, filename), 'r').read().decode('utf-8') @@ -58,17 +140,52 @@ for (dirpath, dirnames, filenames) in os.walk(docs_dir): template = template.replace('{{ anchor }}', anchor) toc += template + '\n' - content = markdown.markdown(text, ['headerid']) + content = markdown.markdown(text, ['headerid']) # generate the markdown content + # ======================================================================================================================== build_dir = os.path.join(html_dir, dirpath.lstrip(docs_dir)) + # ive added this if statement as the above command doesnt seem to be working correctly ==================================== + if dirpath != docs_dir: + build_path = dirpath.lstrip(docs_dir) + build_dir = html_dir + build_path + # ======================================================================================================================== + build_file = os.path.join(build_dir, filename[:-3] + '.html') if not os.path.exists(build_dir): os.makedirs(build_dir) - output = page.replace('{{ content }}', content).replace('{{ toc }}', toc).replace('{{ base_url }}', base_url).replace('{{ suffix }}', suffix).replace('{{ index }}', index) + + output = new_page.replace('{{ content }}', content).replace('{{ toc }}', toc).replace('{{ base_url }}', base_url).replace('{{ suffix }}', suffix).replace('{{ index }}', index) + + #add project title + output = output.replace('{{ project_title }}', project_title).replace('{{ version_number }}', conf['version_number']).replace('{{ navigation }}', navigation) + output = output.replace('{{ page_id }}', filename[:-3]) - output = re.sub(r'a href="([^"]*)\.md"', r'a href="\1%s"' % suffix, output) - output = re.sub(r'
    :::bash', r'
    ', output)
+        output = re.sub(r'a href="([^"]*)\.md"', r'a href="\1%s"' % suffix, output)  # Go through all links and remove MD suffixes
+        output = re.sub(r'
    :::bash', r'
    ', output)  # next two lines about adding in pretty print code highlights
         output = re.sub(r'
    ', r'
    ', output)
         output = re.sub(r'', code_label, output)
+
         open(build_file, 'w').write(output.encode('utf-8'))
+
+    # ========================================================================================================================
+
+    #loop through and convert files
+    for section in conf['nav']:
+        # does this section have sub pages?
+        if 'pages' not in section:
+            convert_file(section['file'])
+        else:
+            for page in section['pages']:
+                convert_file(page['file'])
+
+
+
+# output messages if options are missing
+if not options.conf_file_path:
+    print '\tYou did not specifiy a YAML source config file. Do this using -c or --configfile'
+else:
+    if  os.path.splitext(options.conf_file_path)[1] == '.yaml':  # get the file type
+        create_files(options.conf_file_path)
+    else:
+        print '\tYou did not specifiy a YAML source config file.'