Development Instructions

Home | GettingStarted | Contributing | Development Instructions | Code of Conduct

Development Instructions

Read GettingStarted and Contributing guides first.

xml2rfc Docker image

The easiest way to set up a development environment is using the provided Docker image. Run the following command on a separate terminal to build and start a docker environment:

./run.sh

This brings up a bash shell and the Docker image is equipped with all the dependencies required for xml2rfc including fonts. This binds your current working directory to the docker image using -v ${PWD}:/root/xml2rfc.

Create a working branch

Next, create a working branch from your fork and switch to the working branch. See Creating a Fork and Create a Local Branch sections in the Contributing guide for more information.

Run yestests

The xml2rfc test suite updates the dates of valid test results every time you run the test suite. Because of this reason, run the yestests before you change anything. You can run yestests with the following command.

tox -e py310 -- yestests

py38 is the Python version (Python 3.8) that you want to run tests on this can be anything from py37, py38, py39, py310. For the purpose of running yestests and initial testing, running tests on a single Python version is sufficient.

When yestests are complete, commit the changes from tests to your branch. NOTE: You have to do this from your different terminal on your working directory or using your favourite git tool.

git commit tests -m "chore: Run yestests"

Change, test & carry on

Now your branch is ready for changes. Do the appropriate changes and test them with the Python version of your choosing. If you use: tox -e py38, tox will wait for your input on any output changes. It might be easier to run tox -e py38 yestests and inspect the test output for differences.

You can run only a certain set of tests with tox. Inspect Makefile for test names. For example, run only index tests:

tox -e py310 -- indextest

When you are happy with the changes. Run tests on all supported python environments with the following command:

tox -e py37,py38,py39,py310

Push your changes and create PR. See Create a Pull Request section in the Contributing guide for more information.

Source code breakdown

This is not a complete breakdown of xml2rfc source code but rather an introduction of the important places to lookout.

File/directory	Purpose
xml2rfc/	This directory contains all the Python files for the xml2rfc.
xml2rfc/run.py	This file defines the xml2rfc commandline options.
xml2rfc/writers/text.py	Text rendering logic
xml2rfc/writers/html.py	HTML rendering logic, used for PDF rending too.
xml2rfc/writers/pdf.py	PDF rendering logic.
xml2rfc/writers/preptool.py	Prep tool logic.
xml2rfc/writers/v2v3.py	v2v3 conversion logic.
xml2rfc/data/xml2rfc.css	CSS used by HTML & PDF.
xml2rfc/data/v3.rng	xml2rfc v3 RELAX NG schema.
xml2rfc/templates/doc.yaml	xml2rfc documentation. This is used to create the manpage as well.
tests/input/	Input files for the test suite. See Makefile for how these are used.