Specifying Configurations for Yaydoc with .yaydoc.yml

Like many continuous integration services, Yaydoc also reads configurations from a YAML file. To get started with Yaydoc the first step is to create a file named .yaydoc.yml and specify the required options. Recently the yaydoc team finalized the layout of the file. You can still expect some changes as the projects continues to grow on but they shall not be major ones. Let me give you an outline of the entire layout before describing each in detail. Overall the file is divided into four sections.

  • metadata
  • build
  • publish
  • extras

For the first three sections, their intention is pretty clear from their names. The last section extras is meant to hold settings related to integration to external services.

Following is a description of config options under the metadata section and it’s example usage.

Key Description Default

The author of the repository. It is used to construct the copyright text.


The name of the project. This would be displayed on the generated documentation.

Name of the repository

The version of the project. This would be displayed alongside the project name

Current UTC date

If true, the logs generated would be a little more verbose. Can be one of true|false.

  author: FOSSASIA
  projectname: Yaydoc
  version: development
  debug: true

Following is a description of config options under the build section and it’s example usage.

Key Description Default

The theme which should be used to build the documentation. It can one of the built-in themes or any custom sphinx theme from PyPI. Note that for PyPI themes, you need to specify the distribution name and not the package name


This is the path which would be scanned for markdown and reST files. Also any static content such as images referenced from embedded html in markdown should be placed under a _static directory inside source. Note that the README would always be included in the starting page irrespective of source from the auto-generated index


The path to an image to be used as logo for the project. The path specified should be relative to the source directory.


The markdown flavour which should be used to parse the markdown documents. Possible values for this are markdown, markdown_strict, markdown_phpextra, markdown_github, markdown_mmd and commonmark. Note that currently this option is only used for parsing any included documents using the mdinclude directive and it’s unlikely to change soon.


Any python modules or packages which should be mocked. This only makes sense if the project is in python and uses autodoc has C dependencies.


If enabled, Yaydoc will crawl your repository and try to extract API documentation. Provides attributes for specifying the language and source path. Currently supported languages are java and python

  theme: sphinx_fossasia_theme
  source: docs
  logo: images/logo.svg
  markdown_flavour: markdown_github
    - numpy
    - scipy
    - language: python
      source: modules
    - language: java
    - url: <URL of Subproject 1>
      source: doc
    - url: <URL of subproject 2>

Following is a description of config options under the publish section and it’s example usage.

Key Description Default

It provides a attribute url whose value is written in a CNAME file while publishing to github pages.


It provides an app_name attribute which is used as the name of the heroku app. Your docs would be deployed at <app_name>.herokuapp.com

    url: yaydoc.fossasia.org
    app_name: yaydoc 

Following is a description of config options under the extras section and it’s example usage.

Key Description Default

This can be used to include swagger API documentation in the build. The attribute url should point to a valid swagger json file. It also accepts an additional parameter ui which for now only supports swagger.


It takes an attribute path and can include javadocs from the repository.

    url: http://api.susi.ai/docs/swagger.json
    ui: swagger
    path: 'src/'