Skip to content

Commit

Permalink
Add convert_lsstdoc_tex to use lsstdoc macros
Browse files Browse the repository at this point in the history 
This lets us gracefully process common lsstdoc macros with pypandoc. The
new convert_lsstdoc_tex is prefixes the content with lsstdoc macros
before calling convert_text for the actual conversion.

The lsstdoc macros are mirrored by metasrc in metasrc.tex.lsstmacros.

Note: this lets us successfully process the test LDM-151 abstract.
  • Loading branch information
@jonathansick
jonathansick committed Sep 22, 2017
1 parent 3cbd820 commit a043056
Show file tree
Hide file tree
Showing 5 changed files with 248 additions and 24 deletions.
52 changes: 52 additions & 0 deletions metasrc/pandoc/convert.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@

import pypandoc

from ..tex.lsstmacros import LSSTDOC_MACROS


def ensure_pandoc(func):
"""Decorate a function that uses pypandoc to ensure that pandoc is
Expand Down Expand Up @@ -103,3 +105,53 @@ def convert_text(content, from_fmt, to_fmt, deparagraph=False, mathjax=False,
output = pypandoc.convert_text(content, to_fmt, format=from_fmt,
extra_args=extra_args)
return output


def convert_lsstdoc_tex(
content, to_fmt, deparagraph=False, mathjax=False,
smart=True, extra_args=None):
"""Convert lsstdoc-class LaTeX to another markup format.
This function is a thin wrapper around `convert_text` that automatically
includes common lsstdoc LaTeX macros.
Parameters
----------
content : `str`
Original content.
to_fmt : `str`
Output format for the content (see https://pandoc.org/MANUAL.html).
For example, 'html5'.
deparagraph : `bool`, optional
If `True`, then we run the
`metasrc.pandoc.filters.deparagraph.deparagraph` filter to remove the
paragraph (``<p>``, for example) tags around a single paragraph of
content. That filter does not affect content that consists of multiple
blocks (several paragraphs, or lists, for example). Default is `False`.
mathjax : `bool`, optional
If `True` then Pandoc will markup output content to work with MathJax.
Default is False.
smart : `bool`, optional
If `True` (default) then ascii characters will be converted to unicode
characters like smart quotes and em dashes.
extra_args : `list`, optional
Sequence of Pandoc arguments command line arguments (such as
``'--normalize'``). The ``deparagraph``, ``mathjax``, and ``smart``
arguments are convenience arguments that are equivalent to items
in ``extra_args``.
Returns
-------
output : `str`
Content in the output (``to_fmt``) format.
Notes
-----
This function will automatically install Pandoc if it is not available.
See `ensure_pandoc`.
"""
augmented_content = '\n'.join((LSSTDOC_MACROS, content))
return convert_text(
augmented_content, 'latex', to_fmt,
deparagraph=deparagraph, mathjax=mathjax,
smart=smart, extra_args=extra_args)
18 changes: 9 additions & 9 deletions metasrc/tex/lsstdoc.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
import logging

from .commandparser import LatexCommand
from ..pandoc.convert import convert_text
from ..pandoc.convert import convert_lsstdoc_tex
from .scraper import get_macros
from .texnormalizer import read_tex_file, replace_macros

Expand Down Expand Up @@ -172,8 +172,8 @@ def format_title(self, format='html5', deparagraph=True, mathjax=False,
if self.title is None:
return None

output_text = convert_text(
self.title, 'latex', 'html5',
output_text = convert_lsstdoc_tex(
self.title, 'html5',
deparagraph=deparagraph,
mathjax=mathjax,
smart=smart,
Expand Down Expand Up @@ -207,8 +207,8 @@ def format_short_title(self, format='html5', deparagraph=True,
if self.short_title is None:
return None

output_text = convert_text(
self.short_title, 'latex', 'html5',
output_text = convert_lsstdoc_tex(
self.short_title, 'html5',
deparagraph=deparagraph,
mathjax=mathjax,
smart=smart,
Expand Down Expand Up @@ -242,8 +242,8 @@ def format_abstract(self, format='html5', deparagraph=False, mathjax=False,
if self.abstract is None:
return None

output_text = convert_text(
self.abstract, 'latex', 'html5',
output_text = convert_lsstdoc_tex(
self.abstract, 'html5',
deparagraph=deparagraph,
mathjax=mathjax,
smart=smart,
Expand Down Expand Up @@ -275,8 +275,8 @@ def format_authors(self, format='html5', deparagraph=True, mathjax=False,
"""
formatted_authors = []
for latex_author in self.authors:
formatted_author = convert_text(
latex_author, 'latex', 'html5',
formatted_author = convert_lsstdoc_tex(
latex_author, 'html5',
deparagraph=deparagraph,
mathjax=mathjax,
smart=smart,
Expand Down
165 changes: 165 additions & 0 deletions metasrc/tex/lsstmacros.py
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,165 @@
"""LaTeX macros provided by the lsstdoc class. Metasrc mirrors these macros
to allow Pandoc to resolve them.
"""

__all__ = ['LSSTDOC_MACROS']

LSSTDOC_MACROS = r"""\newcommand{\latex}{LaTeX}
\newcommand{\docType}{LSST Document}
\newcommand{\CU}{DM}
\newcommand{\DU}{}
\newcommand{\setLSSTDU}[1]{\renewcommand{\DU}{-#1}}
\newcommand{\byte}{b}
\def\aaps{A\&AS} % Astronomy and Astrophysics Suplement
\def\aap{A\&A} % Astronomy and Astrophysics
\def\ssr{Space~Sci.~Rev.} % Space Science Reviews
\def\apj{ApJ} % Astrophysical Journal
\def\apjs{ApJS} % Astrophysical Journal Supplement
\def\aj{AJ} % Astronomical Journal
\def\mnras{MNRAS} % Monthly Notices of the RAS
\def\araa{ARA\&A} % Annual Review of Astron and Astrophys
\def\nat{Nature} % Nature
\def\apjl{ApJ} % Astrophysical Journal, Letters
\def\icarus{Icarus} % Icarus
\def\prd{Phys.~Rev.~D} % Physical Review D
\def\physrep{Phys.~Rep.} % Physics Reports
\def\pasp{PASP} % Publications of the Astronomical Society of the Pacific
\def\procspie{Proc.\ SPIE} % Proceedings of the SPIE
\newcommand{\pasa}{PASA} % Publications of the Astronomical Society of Australia
\newcommand{\ao}{Appl.~Opt.} % Applied Optics
\def\degr{\hbox{$^\circ$}}
\def\arcmin{\hbox{$^\prime$}}
\def\arcsec{\hbox{$^{\prime\prime}$}}
\def\fs{\hbox{$.\!\!^{\rm s}$}}
\def\fdg{\hbox{$.\!\!^\circ$}}
\def\farcm{\hbox{$.\mkern-4mu^\prime$}}
\def\farcs{\hbox{$.\!\!^{\prime\prime}$}}
\def\sun{\hbox{$\odot$}}
\newcommand{\pu}[2]{\ensuremath{#1\,\mbox{#2}}}
\newcommand{\secs}[1]{\pu{#1}{s}}
\newcommand{\uas}[1]{\pu{#1}{$\mu$as}}
\newcommand{\muas}[1]{\pu{#1}{$\mu$as}}
\newcommand{\muasonly}{\ensuremath{\mu\mbox{as}}}
\newcommand{\inp}[1]{{\tt #1}}
\newcommand{\prog}[1]{{\it #1}}
\newcommand{\secref}[1]{Section~\ref{#1}}
\newcommand{\appref}[1]{Appendix~\ref{#1}}
\newcommand{\partref}[1]{Part~\ref{#1}}
\newcommand{\tabref}[1]{Table~\ref{#1}}
\newcommand{\figref}[1]{Figure~\ref{#1}}
\newcommand{\eqnref}[1]{Eq.~\ref{#1}}
\newcommand{\reqref}[1]{Req.~\ref{#1}}
\newcommand{\actref}[1]{AI~\ref{#1}}
\newcommand{\class}[1]{{\it #1}}
\newcommand{\pack}[1]{{\em #1}}
\newcommand{\property}[1]{{\em #1}}
\newcommand{\method}[1]{{\em #1}}
\newcommand{\file}[1]{{\em #1}}
\newcommand{\directory}[1]{{\em #1}}
%\providecommand{\code}[1]{{\tt #1}}
% \renewcommand{\vec}[1]{\ensuremath{\mathchoice{\mbox{\boldmath$\displaystyle#1$}}
% {\mbox{\boldmath$\textstyle#1$}}
% {\mbox{\boldmath$\scriptstyle#1$}}
% {\mbox{\boldmath$\scriptscriptstyle#1$}}}}
\newcommand{\vstretch}[1]{\vspace*{\stretch{#1}}}
\newcommand{\code}[1]{\texttt{#1}}
\newcommand{\Alert}{\code{Alert}\xspace}
\newcommand{\Alerts}{\code{Alerts}\xspace}
\newcommand{\DIASource}{\code{DIA\-Source}\xspace}
\newcommand{\DIASources}{\code{DIA\-Sources}\xspace}
\newcommand{\DIAObject}{\code{DIA\-Object}\xspace}
\newcommand{\DIAObjects}{\code{DIA\-Objects}\xspace}
\newcommand{\DB}{{Level 1 database}\xspace}
\newcommand{\DR}{{Level 2 database}\xspace}
\newcommand{\Object}{\code{Object}\xspace}
\newcommand{\Objects}{\code{Objects}\xspace}
\newcommand{\Source}{\code{Source}\xspace}
\newcommand{\Sources}{\code{Sources}\xspace}
\newcommand{\ForcedSource}{\code{Forced\-Source}\xspace}
\newcommand{\ForcedSources}{\code{Forced\-Sources}\xspace}
\newcommand{\CoaddSource}{\code{Coadd\-Source}\xspace}
\newcommand{\CoaddSources}{\code{Coadd\-Sources}\xspace}
\newcommand{\SSObject}{\code{SS\-Object}\xspace}
\newcommand{\SSObjects}{\code{SS\-Objects}\xspace}
\newcommand{\VOEvent}{\code{VO\-Event}\xspace}
\newcommand{\VOEvents}{\code{VO\-Events}\xspace}
\newcommand{\transSNR}{5\xspace}
% Command to link to a document in Docushare. Pass an LSST document handle as argument, or a document number.
% This will not result in a references entry.
\newcommand{\ds}[2]{{\color{blue} \href{https://docushare.lsst.org/docushare/dsweb/Get/#1}{#2}}\xspace}
% These used to be `citeds` commands. Now just plain text with hyperlinks.
\newcommand{\SRD}{\href{https://docushare.lsst.org/docushare/dsweb/Get/LPM-17}{SRD}}
\newcommand{\DPDD}{\href{https://docushare.lsst.org/docushare/dsweb/Get/LSE-163}{DPDD}}
\newcommand{\LSR}{\href{https://docushare.lsst.org/docushare/dsweb/Get/LSE-29}{LSR}}
\newcommand{\OSS}{\href{https://docushare.lsst.org/docushare/dsweb/Get/LSE-30}{OSS}}
\newcommand{\DMSR}{\href{https://docushare.lsst.org/docushare/dsweb/Get/LSE-61}{DMSR}}
\newcommand{\appsUMLdomain}{https://docushare.lsst.org/docushare/dsweb/Get/\href{LDM-133}{LDM-133}}
\newcommand{\appsUMLusecase}{\href{https://docushare.lsst.org/docushare/dsweb/Get/LDM-134}{LDM-134}}
\newcommand{\SUI}{\href{https://docushare.lsst.org/docushare/dsweb/Get/LDM-131}{SUID}}
\newcommand{\DMSD}{\href{https://docushare.lsst.org/docushare/dsweb/Get/LDM-148}{DMSD}}
\newcommand{\MOPSD}{\href{https://docushare.lsst.org/docushare/dsweb/Get/LDM-156}{MOPSD}}
\newcommand{\DMMD}{\href{https://docushare.lsst.org/docushare/dsweb/Get/LDM-152}{DMMD}}
\newcommand{\DMOps}{\href{https://docushare.lsst.org/docushare/dsweb/Get/LDM-230}{DM OpsCon}}
\newcommand{\SDQAP}{\href{https://docushare.lsst.org/docushare/dsweb/Get/LSE-63}{LSE-63}}
\newcommand{\NewPCP}{\href{https://docushare.lsst.org/docushare/dsweb/Get/LSE-180}{LSE-180}}
\newcommand{\UCAL}{\href{https://docushare.lsst.org/docushare/dsweb/Get/Document-15125}{UCAL}}
\newcommand{\wbsSFM}{WBS 02C.03.01}
\newcommand{\wbsAssocP}{WBS 02C.03.02}
\newcommand{\wbsAP}{WBS 02C.03.03}
\newcommand{\wbsDiffim}{WBS 02C.03.04}
\newcommand{\wbsMOPS}{WBS 02C.03.06}
\newcommand{\wbsSDQAP}{WBS 02C.01.02.02}
\newcommand{\wbsSDQAT}{WBS 02C.01.02.02}
\newcommand{\wbsSPT}{WBS 02C.01.02.03}
\newcommand{\wbsPSF}{WBS 02C.04.03}
\newcommand{\wbsCoadd}{WBS 02C.04.04}
\newcommand{\wbsDetDeblend}{WBS 02C.04.05}
\newcommand{\wbsObjChar}{WBS 02C.04.06}
\newcommand{\wbsAFW}{WBS 02C.03.05, 02C.04.01}
\newcommand{\wbsCPP}{WBS 02C.04.02}
\newcommand{\wbsPhotoCal}{WBS 02C.03.07}
\newcommand{\wbsAstroCal}{WBS 02C.03.08}
%%% Command's for merging Robert's document, at least temporarily.
%%% Some of these will be removable, some may not be.
\renewcommand{\c}{\textit{c.}\xspace}
\newcommand{\eg}{\textit{e.g.}\xspace}
\newcommand{\etc}{\textit{etc.}\xspace}
\newcommand{\ie}{\textit{i.e.}\xspace}
\renewcommand{\th}{\ensuremath{^{\mbox{\tiny th}}}\xspace}
\newcommand{\Nb}{\textit{N.b.}\xspace}
\newcommand{\nb}{\textit{n.b.}\xspace}
\DeclareBoldMathCommand\xib{\xi}
\DeclareBoldMathCommand\zerob{0}
\newcommand{\cameraTeam}{\textbf{Camera Team deliverable}\\}
\newcommand{\TBD}{\textit{T.B.D.}\xspace}
\newcommand{\myLabel}[2]{\def\@currentlabel{#2}\label{#1}}
\newcommand{\appRef}[1]{App. \ref{app:#1}}
\newcommand{\secRef}[1]{Sec. \ref{sec:#1}}
\newcommand{\rednote}[1]{{\color{red} (#1)}}
\newcommand{\alg}{\\ \textbullet\xspace Algorithmic component: }
\newcommand{\fefiftyfive}{$^{55}$Fe\xspace}
\newcommand{\bfeffect}{``brighter-fatter effect"}
\newcommand{\auxtelescope}{auxiliary/Calpyso/calibration telescope\xspace}
\newcommand{\secsymbol}{§}
\newcommand{\xxx}{{\color{red} xxx}\xspace}
\newcommand{\dragons}{ {\color{blue} \textbf{\textit{Here be dragons...}}}}
\newcommand{\mysubitem}{\subitem \textendash\xspace}
\newcommand{\smalltilde}{\raise.26ex\hbox{$\scriptstyle\mathtt{\sim}$}}
\newcommand{\electron}{$e^{-}$}
\newcommand{\oldtext}[1]{{\color{red} #1}}
\newcommand{\newtext}[1]{{\color{blue} #1}}
\newcommand{\jira}[1]{\href{https://jira.lsstcorp.org/browse/#1}{#1}}
\newcommand{\uc}[1]{\texttt{#1}}
"""
3 changes: 2 additions & 1 deletion setup.cfg
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@ exclude =
docs/conf.py,
**/*/__init__.py,
version.py,
metasrc/_version.py
metasrc/_version.py,
metasrc/tex/lsstmacros.py

[tool:pytest]
addopts = --flake8 --doctest-modules metasrc tests
Expand Down
34 changes: 20 additions & 14 deletions tests/test_lsstdoc_ldm_151.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,21 +53,27 @@
"design of the scientific aspects of those pipelines."
)

# NOTE: this expected output accounts for pandoc dropping unknown commands
# like "\SRD". Really we need to fix this.
HTML_ABSTRACT = (
"<p>The LSST Science Requirements Document (the LSST ) specifies a "
"set of data product guidelines, designed to support science goals "
"envisioned to be enabled by the LSST observing program. "
"Following these guidlines, the details of these data products have "
"been described in the LSST Data Products Definition Document (), "
"and captured in a formal flow-down from the via the LSST System "
"Requirements (), Observatory System Specifications (), to the "
"Data Management System Requirements (). "
"The LSST Data Management subsystem’s responsibilities include the "
"design, implementation, deployment and execution of software pipelines "
"necessary to generate these data products. This document describes the "
"design of the scientific aspects of those pipelines.</p>\n"
'<p>The LSST Science Requirements Document (the LSST '
'<span><a href="https://docushare.lsst.org/docushare/dsweb/Get/LPM-17">'
'SRD</a></span>) specifies a set of data product guidelines, designed to '
'support science goals envisioned to be enabled by the LSST observing '
'program. Following these guidlines, the details of these data products '
'have been described in the LSST Data Products Definition Document '
'(<span><a href="https://docushare.lsst.org/docushare/dsweb/Get/'
'LSE-163">DPDD</a></span>), and captured in a formal flow-down from '
'the <span><a href="https://docushare.lsst.org/docushare/dsweb/Get/'
'LPM-17">SRD</a></span>via the LSST System Requirements (<span>'
'<a href="https://docushare.lsst.org/docushare/dsweb/Get/LSE-29">'
'LSR</a></span>), Observatory System Specifications (<span>'
'<a href="https://docushare.lsst.org/docushare/dsweb/Get/LSE-30">'
'OSS</a></span>), to the Data Management System Requirements '
'(<span><a href="https://docushare.lsst.org/docushare/dsweb/Get/'
'LSE-61">DMSR</a></span>). The LSST Data Management subsystem’s '
'responsibilities include the design, implementation, deployment and '
'execution of software pipelines necessary to generate these data '
'products. This document describes the design of the scientific aspects '
'of those pipelines.</p>\n'
)

IS_DRAFT = False
Expand Down

0 comments on commit a043056

Please sign in to comment.