learn.adacore.com

Sources for AdaCore's learn.adacore.com website

---

Requirements

This project requires Vagrant and VirtualBox

Getting started

To setup for development run:

$ vagrant up

This will spin up two VMs:

• web: Is the build system for the frontend web content. This includes the webpack build system and sphinx build.

• epub: Is the publishing server. This includes all packages needed to generate the learn website.

To build and start the development server for the frontend, run:

$ vagrant ssh web

# The following commands will be run inside the vm

$ source /vagrant/venv/bin/activate
$ cd /vagrant/frontend
$ pnpm run dev

This will run webpack on the typescript and scss, then sphinx for the rst using make local which will point the widgets at 127.0.0.1:8000

You can then point your browser on your host to 127.0.0.1:8080 to see the learn website being served from vagrant.

Building a single course or lab (faster dev builds)

By default pnpm run dev rebuilds the entire content tree. If you are working on a single unit you can limit both the Sphinx build and the watched file set to that unit by setting the UNIT environment variable:

# Inside the web VM, in /vagrant/frontend:
UNIT=courses/intro-to-ada          pnpm run dev
UNIT=labs/intro-to-ada             pnpm run dev

You can also invoke the Sphinx step directly without the webpack server:

make local UNIT=courses/intro-to-ada

UNIT must be a path relative to the content/ directory. Every unit with a conf.ini file at its root is supported (all courses, labs, and booklets). When UNIT is unset the behaviour is unchanged: the full site is built.

Generate content for publishing

To build and start the publishing server, run:

$ vagrant ssh epub

# The following commands will be run inside the VM

$ cd /vagrant
$ source venv/bin/activate
$ make site

This will build the content for the learn website. You can find it in the /vagrant/frontend/dist directory.

Once you have generated the content for the website, you can test it by coping the files (from your local clone of the repository) to a temporary folder and starting a local server. For example:

LEARN_TEST=$(mktemp -d)

rsync -avz ./frontend/dist/html/       ${LEARN_TEST}/
rsync -avz ./frontend/dist/pdf_books/  ${LEARN_TEST}/pdf_books/
rsync -avz ./frontend/dist/epub_books/ ${LEARN_TEST}/epub_books/
rsync -avz ./frontend/dist/zip/        ${LEARN_TEST}/zip/

rm -r ${LEARN_TEST}/_sources
rm -r ${LEARN_TEST}/_plantuml

( cd ${LEARN_TEST} && python3 -m http.server 8001 )

You can then point your browser on your host to 127.0.0.1:8001 to see the learn website being served from the local Python-based HTTP server.

Testing the source-code examples

The ReST files found in the content directory have .. code:: ada blocks that contain source-code examples. To test the expected behavior of those examples, a test script called compile_blocks.py is available, as well as the rst_code_example_pipeline package.

To make use of this test infrastructure, the best approach is to start the Vagrant publishing server (epub). The Python environment is configured automatically during provisioning.

Using the compile_blocks.py script

After the environment is set, running compile_blocks.py --help displays the help message:

python3 tests/compile_blocks.py --help

To test the code examples from a specific course, select the ReST files from that course and specify them as arguments to the compile_blocks.py script. For example, to test the Introduction to Ada course, run:

python3 tests/compile_blocks.py \
  $(find ../content/courses/intro-to-ada/ -name '*.rst')

Verbose mode

For more verbosity, just add the --verbose switch. For example:

python3 tests/compile_blocks.py \
  --verbose                     \
  $(find ../content/courses/intro-to-ada/ -name '*.rst')

Keep the build directory

To store the build files in a specific directory, just use the --build-dir switch and specify the directory. Also, use the --keep_files switch to prevent that directory from being deleted after the test is complete. For example:

python3 tests/compile_blocks.py \
  --keep_files                  \
  --build-dir test_output       \
  --verbose                     \
  $(find ../content/courses/intro-to-ada/ -name '*.rst')

Single ReST file

To test a single ReST file, specify just that file instead of multiple ReST files:

python3 tests/compile_blocks.py \
  ../content/index.rst

Single code block

To test just a single code block from the ReST file, use the --code-block-at switch:

python3 tests/compile_blocks.py \
  --code-block-at=28            \
  ../content/courses/intro-to-ada/chapters/imperative_language.rst

Maximum number of columns

To check whether a maximum limit of 80 columns per line is respected in the code examples, use the --max_columns switch:

python3 tests/compile_blocks.py \
  --max-columns 80              \
  ../content/index.rst

Using the rst_code_example_pipeline package

The rst_code_example_pipeline package contains the actual Python modules that are called by the compile_blocks.py script. It's possible to use them directly via the installed entry points:

• extract-code extracts all code blocks and stores into the specified directory;

• check-code checks each code block from the specified directory.

For example, to build the source-code examples from the Introduction to Ada course, run:

extract-code                                       \
  --build-dir test_output                                \
  $(find ../content/courses/intro-to-ada/ -name '*.rst')

check-code                                         \
  --build-dir test_output

For more examples and alternative configurations, please refer to the README of the rst_code_example_pipeline package