Adapt folder layout and finish pandoc integration (#69)

Completes the necessary folder layout rework and refactors pandoc file generation to work together with the rest of the tooling/setup. This finally finishes the pandoc integration to automatically generate teaching docs.

.github/workflows/ci.yml

@@ -20,6 +20,6 @@ jobs:
       run: |
         tools/build/build \
           -d ${{runner.temp}}/output \
-          -z ${{github.ref}} \
+          -v ${GITHUB_REF#refs/*/} \
           -s
     ############################################################

.github/workflows/ci_tool_tests.yml

@@ -0,0 +1,31 @@
+# This action is used to run tests to ensure all tools work like expected.
+
+name: Tool CI
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-20.04
+    strategy:
+      matrix:
+        python-version: [3.7, 3.8, 3.9]
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        pip install -r tools/requirements.txt
+
+    - name: Run unittests
+      run: |
+        cd tools
+        pytest

.github/workflows/release.yml

@@ -20,60 +20,20 @@ jobs:
       shell: bash
       run: tools/build/prebuild
     ############################################################
+    - name: Collect git metadata
+      id: git_metadata
+      run: |
+        echo ::set-output name=VERSION::${GITHUB_REF#refs/tags/v}
     # The following builds the document in multiple formats for deployment.
     - name: Build the document.
       shell: bash
       run: |
         tools/build/build \
           -d ${{runner.temp}}/output \
-          -z ${{github.ref}}
-    ############################################################
-    # The following deploys to a different branch of the same repository
-    # using an access token for authentication.
-    # Note: It is recommended that this approach not be used.
-    #- name: Deploy the built document to a GitHub Pages branch.
-    #  env:
-    #    DEPLOY_TOKEN: ${{secrets.DEPLOY_TOKEN}}
-    #  shell: bash
-    #  run: |
-    #    tools/build/deploy \
-    #      -f \
-    #      -m token \
-    #      -t ${{runner.temp}}/deploy_tmp \
-    #      -i ${{runner.temp}}/output \
-    #      -r mdadams/SG20 \
-    #      -b gh-pages \
-    #      -z ${{github.ref}}
-    ############################################################
-    # The following deploys to a different branch of the same repository
-    # using a deploy (i.e., SSH) key for authentication.
-    - name: Deploy the built document to a GitHub Pages branch.
-      env:
-        DEPLOY_KEY: ${{secrets.DEPLOY_KEY}}
-      shell: bash
-      run: |
-        tools/build/deploy \
-          -f \
-          -m key \
-          -t ${{runner.temp}}/deploy_tmp \
-          -i ${{runner.temp}}/output \
-          -r mdadams/SG20 \
-          -b gh-pages \
-          -z ${{github.ref}}
-    ############################################################
-    # The following deploys to a branch of a different repository
-    # using a deploy (i.e., SSH) key authentication.
-    - name: Deploy the built document to a GitHub Pages branch.
-      env:
-        DEPLOY_KEY: ${{secrets.ALT_DEPLOY_KEY}}
-      shell: bash
-      run: |
-        tools/build/deploy \
-          -f \
-          -m key \
-          -t ${{runner.temp}}/deploy_tmp_2 \
-          -i ${{runner.temp}}/output \
-          -r mdadams/sg20_guidelines_for_teaching_cpp \
-          -b gh-pages \
-          -z ${{github.ref}}
-    ############################################################
+          -v ${{ steps.git_metadata.outputs.VERSION }}
+    - name: Deploy generated content to gh-pages
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ${{runner.temp}}/output
+        keep_files: true

.gitignore

@@ -1 +1,13 @@
 __pycache__/
+
+# Ignore generated files
+sources/contributors.md
+sources/guidelines.epub
+sources/guidelines.html
+sources/guidelines.texi
+sources/guidelines_html/
+sources/knowledge_areas_summary.md
+sources/main.gen.md
+sources/main.pre.md
+sources/spellcheck_expected_sorted.txt
+sources/spellcheck_result.txt

.mailmap

@@ -0,0 +1 @@
+Florian Sattler <vuld3r@gmail.com> <vulder@users.noreply.github.com>

README.md

@@ -8,10 +8,7 @@ This repository contains the source for the document:
 When the repository is tagged, this document is automatically built
 and made available via GitHub Pages at:
 
-  - <https://cplusplus.github.io/SG20/latest> (soon)
-  - <https://mdadams.github.io/sg20_guidelines_for_teaching_cpp/latest>
-    (currently)
-  - <https://mdadams.github.io/SG20/latest> (currently)
+  - <https://cplusplus.github.io/SG20/latest>
 
 # Prerequisites for Building the Document
 

config/spellcheck/ignored_words.txt

@@ -10,6 +10,8 @@ expr
 Florian
 func
 Furst
+Hinnant
+html
 Hyland
 JC
 Krathwohl
@@ -21,7 +23,6 @@ Sattler
 SG
 Stroustrup
 udl
+Vandevoorde
 ver
 Winkel
-Hinnant
-Vandevoorde

tools/old/skeleton.md → skeleton.md

@@ -1,48 +1,41 @@
-# Module name: topic name
+## Module name: topic name
+
 _Skeleton descriptions are typeset in italic text,_
 _so please don't remove these descriptions when editing the topic._
 
-## Overview
+### Overview
 
 _Provides a short natural language abstract of the module’s contents._
 _Specifies the different levels of teaching._
 
-<table>
-  <thead>
-    <th>Level</th>
-    <th>Objectives</th>
-  </thead>
-  <tr>
-    <td>Foundational</td>
-    <td></td>
-  </tr>
-  <tr>
-    <td>Main</td>
-    <td></td>
-  </tr>
-  <tr>
-    <td>Advanced</td>
-    <td></td>
-  </tr>
-</table>
-
-## Motivation
+------------------------------------------------------------------------
+Level             Objective
+----------------- ------------------------------------------------------
+Foundational      ---
+
+Main              ---
+
+Advanced          ---
+
+------------------------------------------------------------------------
+
+### Motivation
 
 _Why is this important?_
 _Why do we want to learn/teach this topic?_
 
-## Topic introduction
+### Topic introduction
 
 _Very brief introduction to the topic._
 
-## Foundational: Using *
+### Foundational: Using *
 
-### Background/Required Knowledge
+#### Background/Required Knowledge
 
 A student:
 
 
-### Student outcomes
+#### Student outcomes
 
 _A list of things "a student should be able to" after the curriculum._
 _The next word should be an action word and testable in an exam._
@@ -56,22 +49,22 @@ A student should be able to:
 4.
 5.
 
-### Caveats
+#### Caveats
 
 _This section mentions subtle points to understand, like anything resulting in
 implementation-defined, unspecified, or undefined behavior._
 
-### Points to cover
+#### Points to cover
 
 _This section lists important details for each point._
 
-## Main: implementing *
+### Main: implementing *
 
-### Background/Required Knowledge
+#### Background/Required Knowledge
 
 * All of the above.
 
-### Student outcomes
+#### Student outcomes
 
 A student should be able to:
 
@@ -81,11 +74,11 @@ A student should be able to:
 4.
 5.
 
-### Caveats
+#### Caveats
 
-### Points to cover
+#### Points to cover
 
-## Advanced
+### Advanced
 
 _These are important topics that are not expected to be covered but provide
 guidance where one can continue to investigate this topic in more depth._

sources/Makefile

@@ -15,26 +15,26 @@ DOC_SPELLCHECK_MUST_PASS = 1
 INSTALL_DIR = $(TOP_DIR)/install
 
 # All of the Markdown source files (that are not generated during build).
-SOURCES = \
-  modules/compile-time-programming/requires-expressions.md \
-  modules/functions/defaulted-parameters.md \
-  modules/functions/user-defined-literals.md \
-  modules/object-model/copy-semantics.md \
-  course_examples.md \
-  disclaimer.md \
-  glossary.md \
+SOURCES = $(shell find . -mindepth 2 -name '*.md')
+
+# Special top-level markdown files
+EXTRA_SOURCES = glossary.md \
   contributing.md \
   introduction.md \
-  main.md \
+  main_raw.md \
   obtaining_document.md \
   references.md \
 
 # The Markdown files that are generated during the build process.
 GENERATED_MARKDOWN = \
   knowledge_areas_summary.md \
+  main.pre.md \
   main.gen.md \
   contributors.md \
 
+# Merge extra sources with detected sources for teaching modules
+SOURCES += $(EXTRA_SOURCES)
+
 ################################################################################
 # Define primary targets.
 ################################################################################
@@ -96,6 +96,7 @@ install: all
 # Some additional configuration.
 ################################################################################
 
+MAIN_GENERATOR= $(TOP_DIR)/tools/build/generate_main.py
 MD_PREPROCESSOR = $(TOP_DIR)/tools/build/preprocessor
 MAKE_MARKDOWN = $(TOP_DIR)/tools/build/make_markdown
 SPELLCHECK_DIR = $(TOP_DIR)/config/spellcheck
@@ -104,14 +105,17 @@ SPELLCHECK_DIR = $(TOP_DIR)/config/spellcheck
 # Preprocessing setup.
 ################################################################################
 
-main.gen.md: $(SOURCES) contributors.md main.md
-	$(MD_PREPROCESSOR) -v $(DOC_VERSION) < main.md > main.gen.md
+main.pre.md: $(SOURCES) contributors.md main_raw.md
+	$(MAIN_GENERATOR) --raw main_raw.md --out main.pre.md --module-folder modules
+
+main.gen.md: $(SOURCES) contributors.md main.pre.md
+	$(MD_PREPROCESSOR) -v $(DOC_VERSION) < main.pre.md > main.gen.md
 
 knowledge_areas_summary.md: $(SOURCES) knowledge_areas.dat
 	$(MAKE_MARKDOWN) < knowledge_areas.dat > knowledge_areas_summary.md
 
 contributors.md:
-	git log --all --pretty="%an" | sort | uniq > contributors.md
+	git log --all --pretty="%aN" | sort | uniq > contributors.md
 
 ################################################################################
 # Establish Pandoc settings.
@@ -163,21 +167,16 @@ guidelines.tex:
 
 spellcheck_result.txt: guidelines.html
 	rm -f $@
-	rm -f spellcheck_expected_sorted.txt
-	sort $(SPELLCHECK_DIR)/ignored_words.txt | \
-	  uniq > spellcheck_expected_sorted.txt
 	PATH="$(TOP_DIR)/tools/build:$$PATH" pandoc --from $(INPUT_FORMAT) \
 	  --lua-filter $(TOP_DIR)/tools/pandoc_filters/spellcheck.lua \
 	  main.gen.md | sort | uniq > $@
-	@status=0; \
-	  diff -q spellcheck_expected_sorted.txt $@ || \
-	  status=1; \
-	  if [ $$status -ne 0 ]; then \
-	      echo "SPELLING ERRORS DETECTED:"; \
-	      diff -u spellcheck_expected_sorted.txt $@ | \
-		  grep '^[+-]'; \
+	  if [ -s $@ ]; then \
+	      echo "DETECTED SPELLING ERRORS:"; \
+	      cat $@ | while read line; do echo "Misspelled '$$line' in:"; \
+	      grep -R "$$line" -n --color=auto --include='*.md' --exclude='main.gen.md'; done; \
+	      sync; \
 	      if [ $(DOC_SPELLCHECK_MUST_PASS) -ne 0 ]; then \
-	          echo "ERROR: spelling errors detected"; \
+	          echo "ERROR: spelling errors detected, cannot proceed!"; \
 	          exit 1; \
 	      else \
 	          echo "WARNING: spelling errors detected"; \

sources/index.html

@@ -1,6 +1,7 @@
 <head>
-  <meta http-equiv="refresh" content="0; URL=https://mdadams.github.io/sg20_guidelines_for_teaching_cpp/latest/" />
+    <meta http-equiv="refresh" content="0; URL=https://cplusplus.github.io/SG20/latest/" />
 </head>
+
 <body>
-  <p>If you are not redirected in five seconds, <a href="https://mdadams.github.io/sg20_guidelines_for_teaching_cpp/latest/">click here</a>.</p>
+    <p>If you are not redirected in five seconds, <a href="https://cplusplus.github.io/SG20/latest/">click here</a>.</p>
 </body>