Skip to content

Documents & Tests

This page describes solutions ice-learn adopts about documentation generation, unit tests and documentation-based test. Note that following commands should be executed in a poetry shell, or prepended by poetry run.

pytest

  • We use pytest for unittesting. For example,
pytest tests/llutil/test_config.py -vs

where -s will print outputs for failed tests.

  • Run specific tests with test_mod.py::TestClass:test_method or test_mod.py::test_function.
pytest tests/llutil/test_multiprocessing.py::test_reduce -v
  • Option -m slow will run tests decorated with the @pytest.mark.slow decorator.
pytest tests/llutil/test_multiprocessing.py -v -m slow
  • Option -m "not slow" will run tests not decorated with the @pytest.mark.slow decorator.
pytest tests/llutil/ -v -m "not slow"

  • See more configurations in pytest.ini.

  • ice.llutil.test has some extensions for conditional tests for conveniency.

xdoctest

We use xdoctest for testing demostration code in docstring. For example,

python -m xdoctest ice/llutil/config.py

or

pytest ice/llutil/ -v --xdoc

lazydocs

We generate markdown documentations from docstring using a modified lazydocs script. For example,

python ./docs/build_docs.py

mkdocs

We generate the documents site from manually written as well as autogenerated markdown using mkdocs, the plugin mkdocs-awesome-pages and the theme mkdocs-material. In the ./docs directory, files in documents are automatically generated by lazydocs, while other subfolders contain manually written docs.

Configuration file is mkdocs.yml. Changing the navigator appearance of the document site requires modifying .pages file in each level of subdirectories.

Run following command locally to preview the site at the root directory of ice-learn project:

mkdocs serve

Run following command to push documents to gh-pages branch (for Github Pages).

mkdocs gh-deploy

See this page for more infomation on deploying documents.