mirror of
https://github.com/encode/django-rest-framework.git
synced 2024-12-03 23:14:07 +03:00
First draft of improved config based markdown converter
This commit is contained in:
Max Hurl
parent
2469cd2c83
commit
299e0d735b
42
docs-settings.yaml
Normal file
42
docs-settings.yaml
Normal file
|
|
@ -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
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
||||
<meta charset="utf-8">
|
||||
<title>Django REST framework</title>
|
||||
<title>{{ project_title }}</title>
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<meta name="description" content="">
|
||||
<meta name="author" content="">
|
||||
|
|
@ -18,6 +18,8 @@
|
|||
<![endif]-->
|
||||
<body onload="prettyPrint()" class="{{ page_id }}">
|
||||
|
||||
{{ navigation }}
|
||||
|
||||
<div class="navbar navbar-inverse navbar-fixed-top">
|
||||
<div class="navbar-inner">
|
||||
<div class="container-fluid">
|
||||
|
|
@ -26,7 +28,7 @@
|
|||
<span class="icon-bar"></span>
|
||||
<span class="icon-bar"></span>
|
||||
</a>
|
||||
<a class="brand" href="{{ base_url }}{{ index }}">Django REST framework</a>
|
||||
<a class="brand" href="{{ base_url }}{{ index }}">{{ project_title }}</a>
|
||||
<div class="nav-collapse collapse">
|
||||
<ul class="nav">
|
||||
<li><a href="{{ base_url }}{{ index }}">Home</a></li>
|
||||
|
|
@ -74,10 +76,10 @@
|
|||
</ul>
|
||||
<ul class="nav pull-right">
|
||||
<li class="dropdown">
|
||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Version: 2.0.0 <b class="caret"></b></a>
|
||||
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Version: {{ version_number }} <b class="caret"></b></a>
|
||||
<ul class="dropdown-menu">
|
||||
<li><a href="#">Trunk</a></li>
|
||||
<li><a href="#">2.0.0</a></li>
|
||||
<li><a href="#">{{ version_number }}</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
|
|
|||
185
mkdocs.py
185
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 = '<li class="main"><a href="#{{ anchor }}">{{ title }}</a></li>'
|
||||
sub_header = '<li><a href="#{{ anchor }}">{{ title }}</a></li>'
|
||||
code_label = r'<a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/djangorestframework/\1"><span class="label label-info">\1</span></a>'
|
||||
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 = '<li class="main"><a href="#{{ anchor }}">{{ title }}</a></li>'
|
||||
sub_header = '<li><a href="#{{ anchor }}">{{ title }}</a></li>'
|
||||
code_label = r'<a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/djangorestframework/\1"><span class="label label-info">\1</span></a>'
|
||||
|
||||
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 = "<ul>{{ content }}</ul>"
|
||||
|
||||
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 = "<li><a href='" + base_url + section['file'][:-3] + suffix + "' >" + section['title'] + "</a></li>"
|
||||
else:
|
||||
# output drop down nav
|
||||
top_nav = "<li>" + section['title'] + " <ul>{{ drop_down }}</ul></li>"
|
||||
|
||||
drop_down = ""
|
||||
for page in section['pages']:
|
||||
inner_nav = "<li><a href='" + base_url + page['file'][:-3] + suffix + "' >" + page['title'] + "</a></li>"
|
||||
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'<pre><code>:::bash', r'<pre class="prettyprint lang-bsh">', 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'<pre><code>:::bash', r'<pre class="prettyprint lang-bsh">', output) # next two lines about adding in pretty print code highlights
|
||||
output = re.sub(r'<pre>', r'<pre class="prettyprint lang-py">', output)
|
||||
output = re.sub(r'<a class="github" href="([^"]*)"></a>', 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.'
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user