Tasks #4: Developers' tools

Other tasks: 1, 2, 3, 4, 5, 6, 7.

General notes

Use your GitLab repository to submit your solutions. Please, use exact filenames as specified in the task name.

Please, respect language requirements of individual tasks. For Python, we expect Python 3 as the default (if you really need to use Python 2, use a proper shebang). For shell scripts, we expect that you will use Bash although none of the tasks requires any use of Bashisms for an efficient solution.

Deadline for this set of tasks is 2020-05-15 AoE, it is required to get at least 9 points from this group.

Tasks description

Simple SSG (7 points)

Tasks in this group are actually revolving around a single program that has to be properly prepared for distribution and its implementation completed.

The main program you are about to work on will be written in Python and will serve as a simple static site generator. Here is a huge list of existing SSGs if you are interested in competition.

Your SSG will be extremely simple, though. It will generate all the pages from a single template and no fancy features, such as built-in web server, will be present.

As things are best shown with examples, please clone teaching/nswi177/2020-summer/upstream/examples again and move into my_ssg/examples/01.

Inside templates/main.j2 is a simple template using Jinja2 engine. If you know HTML, you should be able to identify a typical web page template and also note the {{ parts where variable expansion would be done by Jinja.

Directory content/ then contains source files for web generation. They all have .md extensions as they are written in Markdown with YAML header.

And in directory out/ we can see how the input Markdown files were transformed using the Jinja template into final HTML (note that the files were run through HTML Tidy before being added to the repository). Files from static/ directory were copied as-is.

The overall task is then simple: finish the implementation of the Python program my_ssg that does the actual conversion.

We expect that the program would be called as

my_ssg generate \
    --content content \
    --templates templates \
    --static static \
    --destination out

to generate the output. All the parameters --content, --templates, --static and --destination are not required, the defaults are as above.

That is, if you cd into examples/01 and only execute ../../my_ssg generate without further parameters, it should work too.

Call to my_ssg version should print version of your program.

Store your solution in your repository as usual, inside the 04/ folder. I.e. in 04 directory there will be root of your program directory with files and dirs like my_ssg, README, run_tests.sh, examples ....

We have already implemented a huge portion of the SSG. The skeleton that you have available is able to iterate through all input files and load them. It also parses the YAML header for you.

What is missing is the actual Jinja templating and copying of static files.

We believe that if you are in your first year of studies, you know Python well enough to be able to understand the code quite easily. If you did not have Python in the mandatory courses, you should have at least 3 semesters of programming behind you and reading code in unknown language shall not be a problem for you. In the end, the solution requires about 15 lines of code (honest).

Note that examples from examples/02 does not need to work for you at the moment.

Some useful hints:

• You will need to add |markdownify filter to Jinja for the template to work correctly.
• We use argparse for parsing command-line options. This SO thread might be also useful.
• Module shutil might be useful when copying static files.

Tests (4 points)

Add tests to your program to verify that it works as expected. We do not impose a hard limit on the number of tests but we encourage you to write unit tests (e.g. to test the |markdownify filter) as well as bigger test that would compare the expected output of the whole program execution.

Note that tests that we have provided use nose as the testing framework. Feel free to switch to a different framework if you are more familiar with another one.

04/requirements.txt (2 points)

Provide a proper dependency file for Pip so that your program can be easily tested in a virtual environment.

04/setup.py (2 points)

Provide a setuptools-based installation script for your program. We expect that after install step, my_ssg would be added to some directory in $PATH.

Extension (5 points)

Extend your program with support for access to all pages. That is useful for generating menus, for example. That can be seen in examples/02.