Changeset f8b59e3 in sasview for docs/sphinx-docs

Timestamp:

Aug 16, 2017 10:55:45 AM (7 years ago)

Author:

Paul Kienzle <pkienzle@…>

Branches:

master, ESS_GUI, ESS_GUI_Docs, ESS_GUI_batch_fitting, ESS_GUI_bumps_abstraction, ESS_GUI_iss1116, ESS_GUI_iss879, ESS_GUI_iss959, ESS_GUI_opencl, ESS_GUI_ordering, ESS_GUI_sync_sascalc, magnetic_scatt, release-4.2.2, ticket-1009, ticket-1094-headless, ticket-1242-2d-resolution, ticket-1243, ticket-1249, ticket885, unittest-saveload

Children:

78d0a9b

Parents:

35ddae5 (diff), 940d034 (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.

Message:

Merge branch 'ticket-510' into ticket-639-katex

Location:

docs/sphinx-docs

Files:

• Makefile (modified) (2 diffs)
• build_sphinx.py (modified) (4 diffs)
• convertKaTex.js (added)
• convertMathJax.js (added)
• source/_extensions/mathjax.py (added)
• source/_static/rendermath.js (added)
• source/conf.py (modified) (2 diffs)

docs/sphinx-docs/Makefile

@@ -16 +16 @@
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source-temp
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
@@ -53 +53 @@
         rm -rf source/dev/api
         sphinx-apidoc -o source/dev/api -d 8 ../../src
-        
+
 html: stubs
         $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

docs/sphinx-docs/build_sphinx.py

@@ -324 +324 @@
         print("!!!!NO MODEL DOCS WILL BE BUILT!!!!")
 
-
 def retrieve_bumps_docs():
     """
@@ -360 +359 @@
                      SASVIEW_BUILD])
 
+def build_pdf():
+    """
+    Runs sphinx-build for pdf.  Reads in all .rst files and spits out the final html.
+    """
+    print("=== Build PDF Docs from ReST Files ===")
+    subprocess.call(["sphinx-build",
+                     "-b", "latex", # Builder name. TODO: accept as arg to setup.py.
+                     "-d", os.path.join(SPHINX_BUILD, "doctrees"),
+                     SPHINX_SOURCE,
+                     os.path.join(SPHINX_BUILD, "latex")])
+
+    LATEXDIR = os.path.join(SPHINX_BUILD, "latex")
+    def pdflatex():
+        subprocess.call(["pdflatex", "Sasview.tex"], cwd=LATEXDIR)
+    pdflatex()
+    pdflatex()
+    pdflatex()
+    subprocess.call(["makeindex", "-s", "python.ist", "Sasview.idx"], cwd=LATEXDIR)
+    pdflatex()
+    pdflatex()
+
+    print("=== Copy PDF to HTML Directory ===")
+    source = os.path.join(LATEXDIR, "Sasview.pdf")
+    target = os.path.join(SASVIEW_DOCS, "Sasview.pdf")
+    shutil.copyfile(source, target)
+
 def build():
     """
     Runs sphinx-build.  Reads in all .rst files and spits out the final html.
     """
-    print("=== Build HTML Docs from Rest Files ===")
+    print("=== Build HTML Docs from ReST Files ===")
     subprocess.call(["sphinx-build",
                      "-b", "html", # Builder name. TODO: accept as arg to setup.py.
@@ -375 +400 @@
     copy_tree(html, SASVIEW_DOCS)
 
-    #We are building latex doc on linux only
-    if "linux" in platform:
-        print "=== Build Latex Docs from Rest Files ==="
-        subprocess.call(["sphinx-build",
-                     "-b", "latex", # Builder name. TODO: accept as arg to setup.py.
-                     "-d", os.path.join(SPHINX_BUILD, "doctrees"),
-                     SPHINX_SOURCE,
-                     os.path.join(SPHINX_BUILD, "latex")])
-
-        print "=== Copy Latex Docs to Build Directory ==="
-        latex = os.path.join(SPHINX_BUILD, "latex")
-        copy_tree(latex, SASVIEW_DOCS)
+def fetch_katex(version, destination="_static"):
+    from zipfile import ZipFile
+    import urllib2
+    url = "https://github.com/Khan/KaTeX/releases/download/%s/katex.zip" % version
+    cache_path = "katex_%s.zip" % version
+    if not os.path.exists(cache_path):
+        try:
+            fd_in = urllib2.urlopen(url)
+            with open(cache_path, "wb") as fd_out:
+                fd_out.write(fd_in.read())
+        finally:
+            fd_in.close()
+    with ZipFile(cache_path) as zip:
+        zip.extractall(destination)
+
+def convert_katex():
+    print("=== Preprocess HTML, converting latex to html ===")
+    subprocess.call(["node", "convertKaTex.js", SASVIEW_DOCS])
+
+def convert_mathjax():
+    print("=== Preprocess HTML, converting latex to html ===")
+    subprocess.call(["node", "convertMathJax.js", SASVIEW_DOCS])
+
+def fetch_mathjax():
+    subprocess.call(["npm", "install", "mathjax-node-page"])
+    # TODO: copy fonts from node_modules/mathjax/fonts/HTML-CSS/Tex into static
 
 def rebuild():
@@ -393 +432 @@
     retrieve_user_docs()
     retrieve_bumps_docs()
+    #fetch_katex(version=KATEX_VERSION, destination=KATEX_PARENT)
+    #fetch_mathjax()
     apidoc()
     build()
+    #build_pdf()
+    #convert_katex()
+    #convert_mathjax()
 
     print("=== Done ===")

docs/sphinx-docs/source/conf.py

@@ -36 +36 @@
               'sphinx.ext.coverage',
               'sphinx.ext.mathjax',
+              #'mathjax',  # replacement mathjax that allows a list of paths
               'dollarmath',
               'sphinx.ext.viewcode']
+
+mathjax_path = (
+    'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?'
+    'config=TeX-MML-AM_CHTML')
+
+# For katex uncomment the following
+"""
+#STATIC_PATH = '../../_static/'
+STATIC_PATH = ''
+mathjax_path = [
+    STATIC_PATH + 'katex/katex.min.js',
+    STATIC_PATH + 'katex/contrib/auto-render.min.js',
+    STATIC_PATH + 'rendermath.js'
+]
+mathjax_css = STATIC_PATH + 'katex/katex.min.css'
+"""
+
 
 # Add any paths that contain templates here, relative to this directory.
@@ -201 +219 @@
 # -- Options for LaTeX output --------------------------------------------------
 
+# TODO: seems like angstroms is defined twice.
 LATEX_PREAMBLE=r"""
+\usepackage[utf8]{inputenc}      % Allow unicode symbols in text
+\usepackage{underscore}          % Allow underscore outside math mode
+\usepackage[T1]{fontenc}         % Use underscore character from font
+\newcommand{\lt}{<}              % HTML needs \lt rather than <
+\newcommand{\gt}{>}              % HTML needs \gt rather than >
 \renewcommand{\AA}{\text{\r{A}}} % Allow \AA in math mode
-\usepackage[utf8]{inputenc}      % Allow unicode symbols in text
-\usepackage[T1]{fontenc}      % Taking care of underscores
-\catcode`\_=12                % Moving underscore to category 12
-\newcommand{\lt}{<}           %lower than symbol handling
-\newcommand{\gt}{>}           %greater than symbol handling
+\DeclareUnicodeCharacter {212B} {\AA}                  % Angstrom
 \DeclareUnicodeCharacter {00B7} {\ensuremath{\cdot}}   % cdot
 \DeclareUnicodeCharacter {00B0} {\ensuremath{^\circ}}  % degrees
-\DeclareUnicodeCharacter {212B} {\AA}                  % Angstrom
 """
 latex_elements = {