Yaydoc provides access to a lot of configurable variables which can be set as per requirements to configure various sections of the build process. You can see the entire list of variables in the project’s homepage. Till now the only way to do this was to set appropriate environment variables. Since a web user interface for yaydoc is in development, providing a clean UI was very important. This meant that we could not just create a bunch of input fields for all variables as that could be overwhelming for any new user. So we decided to ask only minimal information in the web form and read other variables if the user chooses to specify from a YAML file in the target repository.
To read a YAML file, we used PyYaml. It is a well established Python package to safely read info from a YAML file and convert it to a Python’s dictionary. Here is the code snippet for that.
def get_yaml_config(): try: with open('.yaydoc.yml', 'r') as file: conf = yaml.safe_load(file) except FileNotFoundError: return {} return conf
The above code snippet returns a dictionary specifying all keys read from the YAML file. Since none of the options are required, we first create a dictionary with all defaults and recursively merges it with the yaml dict. The merging is done using the following code snippet:
for key, value in head.items(): if isinstance(base, dict): if isinstance(value, dict): base[key] = update_dict(base.get(key, {}), value) else: base[key] = head[key] else: base = {key: head[key]} return base
Now you can create a .yaydoc.yml file in the root of your repository and yaydoc would read options from there. Here is a sample yml file.
metadata: author: FOSSASIA projectname: Yaydoc version: development build: doctheme: fossasia_theme docpath: docs/ logo: images/logo.svg markdown_flavour: markdown_github publish: ghpages: docurl: yaydoc.fossasia.org
It should be noted that the layout of the file may change in the future as the project is in active development.