Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
[ADAM-1548] Generate reStructuredText from pandoc markdown.
Resolves #1548. Generates rst documentation from the pandoc markdown. To display
on readthedocs, this generated documentation must be checked in, so we add
integration to jenkins-test that makes sure that the generated docs are not out
of date and fails the build if the markdown changes but the docs don't.
Additionally, this commit adds the `conf.py` needed by readthedocs.
  • Loading branch information
fnothaft committed Jul 27, 2017
1 parent c8a2202 commit 2e18366
Show file tree
Hide file tree
Showing 6 changed files with 3,531 additions and 23 deletions.
1 change: 0 additions & 1 deletion docs/.gitignore

This file was deleted.

62 changes: 40 additions & 22 deletions docs/build.sh
Expand Up @@ -5,6 +5,7 @@ git_version=$(git log -1 --pretty=format:%H)
output_dir="output"
pdf_output="$output_dir/ADAM_${git_version}.pdf"
html_output="$output_dir/ADAM_${git_version}.html"
rst_output="$output_dir/contents.rst"
date_str=$(date '+%Y-%m-%d')

mkdir -p ${output_dir}
Expand All @@ -20,30 +21,47 @@ if [ $? -ne "0" ]; then
exit 0
fi

# Generate reStructuredText of the docs, for pushing to pandoc
pandoc -N -t rst \
--filter pandoc-citeproc \
--highlight-style "$highlight_style" \
--variable mainfont="Georgia" \
--variable sansfont="Arial" \
--variable monofont="Andale Mono" \
--variable fontsize=10pt \
--variable version=$git_version \
--variable listings=true \
--variable title="$title" \
--variable date="$date" \
--variable author="$author" \
--toc \
--bibliography=source/bibliography.bib \
source/*.md -s -S -o $rst_output

# Generate a PDF of the docs
pandoc -N --template=template.tex \
--filter pandoc-citeproc \
--highlight-style "$highlight_style" \
--variable mainfont="Georgia" \
--variable sansfont="Arial" \
--variable monofont="Andale Mono" \
--variable fontsize=10pt \
--variable version=$git_version \
--variable listings=true \
--variable title="$title" \
--variable date="$date" \
--variable author="$author" \
--toc \
--bibliography=source/bibliography.bib \
source/*.md -s -S -o $pdf_output
--filter pandoc-citeproc \
--highlight-style "$highlight_style" \
--variable mainfont="Georgia" \
--variable sansfont="Arial" \
--variable monofont="Andale Mono" \
--variable fontsize=10pt \
--variable version=$git_version \
--variable listings=true \
--variable title="$title" \
--variable date="$date" \
--variable author="$author" \
--toc \
--bibliography=source/bibliography.bib \
source/*.md -s -S -o $pdf_output

# Generate HTML of the docs
pandoc source/*.md -H style.css -s -S --toc \
--mathjax \
--filter pandoc-citeproc \
--bibliography=source/bibliography.bib \
--highlight-style "$highlight_style" \
--variable title="$title" \
--variable date="$date" \
--variable author="$author" \
-o $html_output
--mathjax \
--filter pandoc-citeproc \
--bibliography=source/bibliography.bib \
--highlight-style "$highlight_style" \
--variable title="$title" \
--variable date="$date" \
--variable author="$author" \
-o $html_output
2 changes: 2 additions & 0 deletions docs/output/.gitignore
@@ -0,0 +1,2 @@
*.pdf
*.html
40 changes: 40 additions & 0 deletions docs/output/conf.py
@@ -0,0 +1,40 @@
#
# Licensed to Big Data Genomics (BDG) under one
# or more contributor license agreements. See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership. The BDG licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#

from datetime import datetime

# General information about the project.
project = u'ADAM'
copyright = u'2013 – %i Big Data Genomics' % datetime.now().year
author = u'Big Data Genomics'

# import the relevant latex packages
latex_elements = { 'preamble': '''
\usepackage{amssymb,amsmath}
\usepackage{algorithmic}
\usepackage{algorithm}
''' }

extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.viewcode',
'sphinx.ext.intersphinx',
]

0 comments on commit 2e18366

Please sign in to comment.