Merge pull request #507 from gusthoff/topic/infrastructure/sphinx/pdf…

…_books/20210219

Introducing initial support for compile-time / runtime output for PDF books

.github/workflows/sphinx-content-tests.js.yml

@@ -30,7 +30,17 @@ jobs:
     - name: Install OS Deps
       run: |
         sudo apt-get install -y \
-        graphviz
+        graphviz \
+        texlive-latex-base \
+        texlive-latex-recommended \
+        texlive-latex-extra \
+        texlive-fonts-recommended \
+        texlive-fonts-extra \
+        latexmk \
+        texlive-xetex \
+        fonts-lmodern \
+        fonts-open-sans \
+        fonts-dejavu
     - name: Install dependencies
       run: yarn --frozen-lockfile
     - name: ada-actions/toolchain
@@ -47,3 +57,12 @@ jobs:
       run: make SPHINXOPTS="-W" test_engine
     - name: Run SPHINX content tests
       run: make -k test_content
+    - name: Build PDF books including build/runtime output
+      run: make pdf_books
+    - name: Archive PDF books in artifact
+      uses: actions/upload-artifact@v2
+      with:
+        name: learn-pdf-books
+        path: |
+          frontend/dist/pdf_books
+        retention-days: 1

content/courses/Ada_For_The_Embedded_C_Developer/chapters/01_Introduction.rst

@@ -24,7 +24,7 @@ program in Ada and C:
 
 [C]
 
-.. code:: c cli_input run_button project=Courses.Ada_For_C_Embedded_Dev.Introduction.Add_Angles_C
+.. code:: c cli_input run_button project=Courses.Ada_For_Embedded_C_Dev.Introduction.Add_Angles_C
 
    !main.c
    #include <stdio.h>
@@ -60,7 +60,7 @@ program in Ada and C:
 
 [Ada]
 
-.. code:: ada cli_input run_button project=Courses.Ada_For_C_Embedded_Dev.Introduction.Add_Angles_Ada
+.. code:: ada cli_input run_button project=Courses.Ada_For_Embedded_C_Dev.Introduction.Add_Angles_Ada
 
    with Ada.Command_Line; use Ada.Command_Line;
    with Ada.Text_IO; use Ada.Text_IO;

content/courses/Ada_For_The_Embedded_C_Developer/chapters/02_Perspective.rst

@@ -119,7 +119,7 @@ program:
 
 [C]
 
-.. code:: c run_button manual_chop project=Courses.Ada_For_C_Embedded_Dev.Perspective.Hello_World_C
+.. code:: c run_button manual_chop project=Courses.Ada_For_Embedded_C_Dev.Perspective.Hello_World_C
 
     !main.c
     #include <stdio.h>
@@ -132,7 +132,7 @@ program:
 
 [Ada]
 
-.. code:: ada run_button project=Courses.Ada_For_C_Embedded_Dev.Perspective.Hello_World_Ada
+.. code:: ada run_button project=Courses.Ada_For_Embedded_C_Dev.Perspective.Hello_World_Ada
 
     with Ada.Text_IO;
 
@@ -1945,7 +1945,7 @@ values from :ada:`'a'` to :ada:`'z'`:
     !main.c
     #include <stdio.h>
 
-    void main(void)
+    int main(int argc, const char * argv[])
     {
         char Arr [26];
         char C = 'a';
@@ -2435,7 +2435,7 @@ Pointers to scalar objects in Ada and C look like:
 
 [Ada]
 
-.. code:: ada run_button project=Courses.Ada_For_C_Embedded_Dev.Perspective.Access_To_Scalars
+.. code:: ada run_button project=Courses.Ada_For_Embedded_C_Dev.Perspective.Access_To_Scalars
 
     procedure Main is
        type A_Int is access Integer;
@@ -2446,7 +2446,7 @@ Pointers to scalar objects in Ada and C look like:
 
 [C]
 
-.. code:: c run_button project=Courses.Ada_For_C_Embedded_Dev.Perspective.Pointers_To_Scalars
+.. code:: c run_button project=Courses.Ada_For_Embedded_C_Dev.Perspective.Pointers_To_Scalars
 
     !main.c
     #include <stdlib.h>
@@ -2463,7 +2463,7 @@ In Ada, an initializer can be specified with the allocation by appending
 
 [Ada]
 
-.. code:: ada run_button project=Courses.Ada_For_C_Embedded_Dev.Perspective.Access_Initialization
+.. code:: ada run_button project=Courses.Ada_For_Embedded_C_Dev.Perspective.Access_Initialization
 
     procedure Main is
        type A_Int is access Integer;
@@ -2485,7 +2485,7 @@ objects that have gone out of scope. For example:
 
 [Ada]
 
-.. code:: ada run_button project=Courses.Ada_For_C_Embedded_Dev.Perspective.Access_All
+.. code:: ada run_button project=Courses.Ada_For_Embedded_C_Dev.Perspective.Access_All
 
     procedure Main is
        type A_Int is access all Integer;
@@ -2497,7 +2497,7 @@ objects that have gone out of scope. For example:
 
 [C]
 
-.. code:: c run_button project=Courses.Ada_For_C_Embedded_Dev.Perspective.Access_All_C
+.. code:: c run_button project=Courses.Ada_For_Embedded_C_Dev.Perspective.Access_All_C
 
     !main.c
     int main(int argc, const char * argv[])
@@ -2515,7 +2515,7 @@ the access type as follows:
 
 [Ada]
 
-.. code:: ada run_button project=Courses.Ada_For_C_Embedded_Dev.Perspective.Unchecked_Deallocation
+.. code:: ada run_button project=Courses.Ada_For_Embedded_C_Dev.Perspective.Unchecked_Deallocation
 
     with Ada.Unchecked_Deallocation;
 
@@ -2529,7 +2529,7 @@ the access type as follows:
 
 [C]
 
-.. code:: c run_button project=Courses.Ada_For_C_Embedded_Dev.Perspective.Free
+.. code:: c run_button project=Courses.Ada_For_Embedded_C_Dev.Perspective.Free
 
     !main.c
     #include <stdlib.h>
@@ -2656,7 +2656,7 @@ Here's a first example:
     #include <stdio.h>
     #include "proc.h"
 
-    void main (void)
+    int main(int argc, const char * argv[])
     {
         int v1, v2;
 

content/courses/Ada_For_The_Embedded_C_Developer/chapters/03_Concurrency.rst

@@ -603,7 +603,7 @@ using the Ravenscar profile. For example:
 
 [Ada]
 
-.. code:: ada compile_button project=Courses.Ada_For_C_Embedded_Dev.Concurrency.Ravenscar
+.. code:: ada compile_button project=Courses.Ada_For_Embedded_C_Dev.Concurrency.Ravenscar
     :class: ada-expect-compile-error
 
     package My_Tasks is
@@ -643,7 +643,7 @@ in the main application:
 
 [Ada]
 
-.. code:: ada run_button project=Courses.Ada_For_C_Embedded_Dev.Concurrency.Ravenscar
+.. code:: ada run_button project=Courses.Ada_For_Embedded_C_Dev.Concurrency.Ravenscar
 
     with My_Tasks; use My_Tasks;
 

content/courses/Ada_For_The_Embedded_C_Developer/chapters/04_Embedded.rst

@@ -169,7 +169,7 @@ assembler as well as source-level variables to be used for input and output:
 
 [Ada]
 
-.. code:: ada no_button project=Courses.Ada_For_C_Embedded_Dev.Embedded.Assembly_Code
+.. code:: ada no_button project=Courses.Ada_For_Embedded_C_Dev.Embedded.Assembly_Code
 
     with System.Machine_Code; use System.Machine_Code;
     with Interfaces;          use Interfaces;
@@ -350,7 +350,7 @@ obvious when looking at this code snippet:
 
 [Ada]
 
-.. code:: ada run_button project=Courses.Ada_For_C_Embedded_Dev.Embedded.Fixed_Point
+.. code:: ada run_button project=Courses.Ada_For_Embedded_C_Dev.Embedded.Fixed_Point
 
     package Fixed_Definitions is
 

content/courses/Ada_For_The_Embedded_C_Developer/chapters/08_Performance.rst

@@ -219,6 +219,7 @@ consider the following example in C:
 [C]
 
 .. code:: c manual_chop run_button project=Courses.Ada_For_Embedded_C_Dev.Performance.Division_By_Zero
+    :class: c-run-expect-failure
 
     !main.c
     #include <stdio.h>

content/courses/intro-to-ada/chapters/arrays.rst

@@ -12,7 +12,6 @@ Arrays in Ada are used to define contiguous collections of elements that can be
 selected by indexing. Here's a simple example:
 
 .. code:: ada run_button project=Courses.Intro_To_Ada.Arrays.Greet
-    :class: ada-run
 
     with Ada.Text_IO; use Ada.Text_IO;
 
@@ -72,7 +71,6 @@ to index into the array.
     equivalence between an array and a pointer to its initial element.
 
 .. code:: ada run_button project=Courses.Intro_To_Ada.Arrays.Array_Bounds_Example
-    :class: ada-run
 
     with Ada.Text_IO; use Ada.Text_IO;
 
@@ -113,7 +111,6 @@ Since you can use any discrete type to index an array, enumeration types
 are permitted.
 
 .. code:: ada run_button project=Courses.Intro_To_Ada.Arrays.Month_Example
-    :class: ada-run
 
     with Ada.Text_IO; use Ada.Text_IO;
 
@@ -192,7 +189,7 @@ an element outside of the bounds of the array, you will get a run-time error
 instead of accessing random memory as in unsafe languages.
 
 .. code:: ada run_button project=Courses.Intro_To_Ada.Arrays.Greet_3
-    :class: ada-run, ada-run-expect-failure
+    :class: ada-run-expect-failure
 
     with Ada.Text_IO; use Ada.Text_IO;
 
@@ -317,7 +314,6 @@ in that case, the bounds will need to be provided when creating instances of
 the type.
 
 .. code:: ada run_button project=Courses.Intro_To_Ada.Arrays.Unconstrained_Array_Example
-    :class: ada-run
 
     with Ada.Text_IO; use Ada.Text_IO;
 
@@ -414,7 +410,6 @@ literals, as we can see in the example below.
         end String_Literals;
 
 .. code:: ada run_button project=Courses.Intro_To_Ada.Arrays.Greet_4
-    :class: ada-run
 
     with Ada.Text_IO; use Ada.Text_IO;
 
@@ -439,7 +434,6 @@ type if you supply an initialization, since the bounds can be deduced from the
 initialization expression.
 
 .. code:: ada run_button project=Courses.Intro_To_Ada.Arrays.Greet_5
-    :class: ada-run
 
     with Ada.Text_IO; use Ada.Text_IO;
 
@@ -510,7 +504,8 @@ cases like this one, it is impossible for a compiler to know in the general
 case if you are assigning a value of the correct length, so this violation will
 generally result in a run-time error.
 
-.. attention::
+.. admonition:: Attention
+
     While we will learn more about this later, it is important to know
     that arrays are not the only types whose instances might be of unknown
     size at compile-time.

content/courses/intro-to-ada/chapters/exceptions.rst

@@ -14,7 +14,7 @@ Ada exceptions are not types, but instead objects, which may be
 peculiar to you if you're used to the way Java or Python support
 exceptions. Here's how you declare an exception:
 
-.. code:: ada no_button project=Courses.Intro_To_Ada.Exceptions.Show_Exception
+.. code:: ada compile_button project=Courses.Intro_To_Ada.Exceptions.Show_Exception
 
     package Exceptions is
         My_Except : exception;
@@ -99,7 +99,7 @@ can add it to the statements block of your current subprogram:
           Put ("Cannot open input file");
     end Open_File;
 
-.. attention::
+.. admonition:: Attention
 
     Exception handlers have an important restriction that
     you need to be careful about: Exceptions raised in the declarative

content/courses/intro-to-ada/chapters/generics.rst

@@ -15,7 +15,7 @@ by using the keyword :ada:`generic`. For example:
 .. raph-amiard: We are lacking a definition/link of metaprogramming.
 
 
-.. code:: ada no_button project=Courses.Intro_To_Ada.Generics.Show_Simple_Generic
+.. code:: ada compile_button project=Courses.Intro_To_Ada.Generics.Show_Simple_Generic
 
     generic
        type T is private;
@@ -37,7 +37,7 @@ want to create an algorithm that works on any integer type, or even on
 any type at all, whether a numeric type or not. The following example
 declares a formal type :ada:`T` for the :ada:`Set` procedure.
 
-.. code:: ada no_button project=Courses.Intro_To_Ada.Generics.Show_Formal_Type_Declaration
+.. code:: ada compile_button project=Courses.Intro_To_Ada.Generics.Show_Formal_Type_Declaration
 
     generic
        type T is private;
@@ -71,7 +71,7 @@ Formal object declaration
 Formal objects are similar to subprogram parameters. They can reference
 formal types declared in the formal specification. For example:
 
-.. code:: ada no_button project=Courses.Intro_To_Ada.Generics.Show_Formal_Object_Declaration
+.. code:: ada compile_button project=Courses.Intro_To_Ada.Generics.Show_Formal_Object_Declaration
 
     generic
        type T is private;
@@ -95,7 +95,7 @@ We don't repeat the :ada:`generic` keyword for the body declaration of a
 generic subprogram or package.  Instead, we start with the actual
 declaration and use the generic types and objects we declared. For example:
 
-.. code:: ada no_button project=Courses.Intro_To_Ada.Generics.Show_Generic_Body_Definition
+.. code:: ada compile_button project=Courses.Intro_To_Ada.Generics.Show_Generic_Body_Definition
 
     generic
        type T is private;