From 067a4d7b2ef9bc4d31296c965286e7d9452d5f03 Mon Sep 17 00:00:00 2001 From: Stephane MICHELOUD Date: Sat, 30 Jan 2021 13:52:01 +0100 Subject: [PATCH 001/152] add pandoc subproject (md2pdf) --- .github/workflows/pandoc.yaml | 23 + pandoc/.dockerignore | 4 + pandoc/Dockerfile | 37 ++ pandoc/README.md | 85 +++ pandoc/build | 38 ++ pandoc/build.bat | 331 ++++++++++ pandoc/data/defaults.yaml | 24 + pandoc/data/filters/include-files.lua | 92 +++ pandoc/data/filters/inlcude-files.txt | 1 + .../explicit-nulls-type-hierarchy.png | Bin 0 -> 57752 bytes pandoc/data/images/external.png | Bin 0 -> 1527 bytes pandoc/data/images/external.txt | 2 + pandoc/data/images/scala-spiral.png | Bin 0 -> 80003 bytes pandoc/data/internals.md | 81 +++ pandoc/data/reference.md | 566 ++++++++++++++++++ pandoc/data/templates/scala.txt | 1 + pandoc/data/templates/scala.xml | 366 +++++++++++ pandoc/data/templates/template.tex | 535 +++++++++++++++++ pandoc/data/usage.md | 58 ++ pandoc/docs/DOCKER.md | 98 +++ pandoc/docs/EXAMPLES.md | 100 ++++ pandoc/docs/PANDOC.md | 71 +++ pandoc/docs/PROJECT.md | 121 ++++ pandoc/docs/TEXLIVE.md | 168 ++++++ pandoc/extras/build_image | 210 +++++++ pandoc/extras/build_image.bat | 218 +++++++ pandoc/extras/install-tex-fonts | 130 ++++ pandoc/extras/install-tex-fonts.bat | 195 ++++++ pandoc/md2pdf | 186 ++++++ pandoc/md2pdf.bat | 194 ++++++ 30 files changed, 3935 insertions(+) create mode 100644 .github/workflows/pandoc.yaml create mode 100644 pandoc/.dockerignore create mode 100644 pandoc/Dockerfile create mode 100644 pandoc/README.md create mode 100644 pandoc/build create mode 100644 pandoc/build.bat create mode 100644 pandoc/data/defaults.yaml create mode 100644 pandoc/data/filters/include-files.lua create mode 100644 pandoc/data/filters/inlcude-files.txt create mode 100644 pandoc/data/images/explicit-nulls/explicit-nulls-type-hierarchy.png create mode 100644 pandoc/data/images/external.png create mode 100644 pandoc/data/images/external.txt create mode 100644 pandoc/data/images/scala-spiral.png create mode 100644 pandoc/data/internals.md create mode 100644 pandoc/data/reference.md create mode 100644 pandoc/data/templates/scala.txt create mode 100644 pandoc/data/templates/scala.xml create mode 100644 pandoc/data/templates/template.tex create mode 100644 pandoc/data/usage.md create mode 100644 pandoc/docs/DOCKER.md create mode 100644 pandoc/docs/EXAMPLES.md create mode 100644 pandoc/docs/PANDOC.md create mode 100644 pandoc/docs/PROJECT.md create mode 100644 pandoc/docs/TEXLIVE.md create mode 100644 pandoc/extras/build_image create mode 100644 pandoc/extras/build_image.bat create mode 100644 pandoc/extras/install-tex-fonts create mode 100644 pandoc/extras/install-tex-fonts.bat create mode 100644 pandoc/md2pdf create mode 100644 pandoc/md2pdf.bat diff --git a/.github/workflows/pandoc.yaml b/.github/workflows/pandoc.yaml new file mode 100644 index 000000000000..cec947d31700 --- /dev/null +++ b/.github/workflows/pandoc.yaml @@ -0,0 +1,23 @@ +name: Pandoc + +on: + push: + pull_request: + +jobs: + build: + runs-on: ubuntu-latest + if: "( github.event_name == 'pull_request' + && !contains(github.event.pull_request.body, '[skip ci]') + && !contains(github.event.pull_request.body, '[skip docs]') + ) + || contains(github.event.ref, 'pandoc') + || contains(github.event.ref, 'master')" + + steps: + - name: Git Checkout + uses: actions/checkout@v2 + + - name: Generate PDF reference documentation + uses: docker://pandoc/latex:2.11.4 + run: ./pandoc/md2pdf reference diff --git a/pandoc/.dockerignore b/pandoc/.dockerignore new file mode 100644 index 000000000000..6ab5a428a959 --- /dev/null +++ b/pandoc/.dockerignore @@ -0,0 +1,4 @@ +docs/ +extras/ +*.bat +README.md diff --git a/pandoc/Dockerfile b/pandoc/Dockerfile new file mode 100644 index 000000000000..0fa388b479af --- /dev/null +++ b/pandoc/Dockerfile @@ -0,0 +1,37 @@ +## Created by mics (https://github.com/michelou/) on December 2020. + +FROM pandoc/ubuntu-latex:2.11.4 + +LABEL md2pdf.author="Stéphane Micheloud " +LABEL md2pdf.description="Create PDF file for Scala 3 documentation" +LABEL md2pdf.version=1.0 + +WORKDIR /app + +COPY ./data ./data +COPY ./src ./src +COPY ./md2pdf . + +## See https://vsupalov.com/docker-arg-env-variable-guide/ +ENV PROJECT_NAME=reference +ENV GIT_HASH= + +ENV TEXLIVE_HOME=/opt/texlive/texdir + +## See https://github.com/openjournals/whedon/blob/master/paperdraft.Dockerfile +RUN tlmgr update --self + +## Install additional LaTeX packages +## Already present: fancyvrb, fontspec, l3backend, l3kernel, l3packages, pgf, unicode-math, xcolor. +RUN tlmgr install \ + dejavu \ + environ \ + gnu-freefont \ + selnolig \ + tcolorbox \ + trimspaces + +RUN echo "#!/bin/bash \n ./md2pdf ${PROJECT_NAME} ${GIT_HASH}" > ./entrypoint.sh +RUN chmod +x ./entrypoint.sh + +ENTRYPOINT [ "./entrypoint.sh" ] diff --git a/pandoc/README.md b/pandoc/README.md new file mode 100644 index 000000000000..0ff51f29068d --- /dev/null +++ b/pandoc/README.md @@ -0,0 +1,85 @@ +# Creating PDF files for the Scala 3 documentation + + +This project aims to generate a *single* PDF file from a collection of [Markdown](https://commonmark.org/) documents, for instance for the [*Scala 3 reference*][scala3_reference] documentation. + +Our solution is built on [Pandoc]; it gets its inputs from two directories and generates a PDF file into the output directory: + + + + + + + + + + + + +
Input directoriesdotty/docs/docs/<project>/
dotty/pandoc/data/		*.md files
Pandoc data files
Output directorydotty/out/pandoc/scala3_<project>.pdf(*)
+ +(*) *``* is one of [`contributing`](https://github.com/lampepfl/dotty/tree/master/docs/docs/contributing), [`internals`](https://github.com/lampepfl/dotty/tree/master/docs/docs/internals), [`reference`](https://github.com/lampepfl/dotty/tree/master/docs/docs/reference) or [`usage`](https://github.com/lampepfl/dotty/tree/master/docs/docs/usage). + +The generated PDF file is more elaborated than its sibling HTML version; unlike the online [*Scala 3 reference*][scala3_reference] documentation available on the [Scala 3 documentation](https://docs.scala-lang.org/scala3/) webpage, the `scala3_reference.pdf` document : +- starts with a *title page* directly followed by a *table of contents* and end with an *appendix*. +- gathers all the "*More details*" sections in the appendix. + +> See document [`PROJECT.md`](docs/PROJECT.md) for further information, e.g. project organisation. + +## Project dependencies [**▲**](#top) + +This project depends on the following software : + +- [Pandoc 2](https://github.com/jgm/pandoc/releases) [[1]](#footnote_01) *([release notes](https://pandoc.org/releases.html))* +- [TeX Live 2020](https://tug.org/texlive/) [[2]](#footnote_02) *([release notes](http://www.tug.org/texlive/doc/texlive-en/texlive-en.html#x1-880009.2))* + +> See documents [`PANDOC.md`](docs/PANDOC.md) and [`TEXLIVE.md`](docs/TEXLIVE.md) for product specific information, e.g. software installation. + +One may also install the following software: + +- [Docker Desktop 3](https://docs.docker.com/get-docker/) [[3]](#footnote_03) *([release notes](https://docs.docker.com/release-notes/))* + +> See document [`DOCKER.md`](docs/DOCKER.md) for further information, e.g. `Dockerfile` usage. + +## Build commands [**▲**](#top) + +We provide two commands for MacOS/Ubuntu as well as their equivalents for MS Windows : +- for *interactive users* :
[`build {