foliantcontrib.checksources 1.0.6

Foliant preprocessor that checks the project for missing and unmentioned files.

CheckSources

CheckSources is a preprocessor that checks the project’s chapters for missing and unmentioned files in the sources directory.

Installation

$ pip install foliantcontrib.checksources

Usage

To enable the preprocessor, add checksources to preprocessors section in the project config:

preprocessors:
    - checksources

Options

• not_in_chapters – a list of files not mentioned in the chapters. No warnings will be displayed for the specified files. This option is useful if you don't need to add some files to the table of contents.

  Files can be specified in this option using Unix-style wildcards. The comparison is case-sensitive.

• strict_check – if a critical error is detected, the build will be failed after applying the preprocessor. Several checks are supported:

  • not_exist – checking the existence of the file. Checks if the file specified in chapters exists (enabled by default);
  • duplicate – checking for duplicate in the chapters.

  To disable strict check, use strict_check: false. And in order to enable all available checks, use strict_check: true.

• disable_warnings – disabling the output of warnings, just like strict_check supports: not_exist and duplicate.

Example of options:

preprocessors:
    - checksources:
        not_in_chapters:
          - tags.md
          - archive/*
        strict_check:
          - not_exist
        disable_warnings:
          - duplicate

Integration with preprocessor Includes

All source files that are not mentioned in chapters or not_in_chapters cause warnings.

However, some files or parts of files may be included by the preprocessor Includes in other files. Warnings about such included files may be unnecessary. CheckSources can process the includes_map.json file generated by Includes and create a list of included files. Files from this list do not cause warnings.

To create a list of included files and avoid unnecessary warnings, enable generation of a map in the project config:

preprocessors:
    - includes:             #includes defined before checksources
        includes_map: true
    - ...
    - checksources

Included files and MultiProject

MultiProject is an extension for Foliant to generate the documentation from multiple sources.

To create a list of included files for the entire project, CheckSources can process the multiproject_includes_map.json file generated by the Includesmap preprocessor from multiple includes_map.json files. If multiproject_includes_map.json and includes_map.json exist for the main project at the same time, CheckSources will use multiproject_includes_map.json.

To create a list of included files for the entire project, enable generation of maps in all configs and combining of maps in the config of the main project.

Config of main project:

preprocessors:              
    - includes:             
        includes_map: true  
    - includesmap           
    - ...
    - checksources

Config of subproject:

preprocessors:              
    - includes:             
        includes_map: true  
    - ...