Star  Watch  Fork  Follow  Issues

Specifying Yaydoc Configurations

In order to generate and deploy documentation for a registered repository, Yaydoc 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.The configuration file is divided into four sections.

metadata

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

Key Description Default
author The author of the repository. It is used to construct the copyright text. user/organization
projectname The name of the project. This would be displayed on the generated documentation. Name of the repository
version The version of the project. This would be displayed alongside the project name Current UTC date
debug If true, the logs generated would be a little more verbose. Can be one of true or false. true
inline_math Whether inline math should be enabled. This only affects markdown documents. false
autoindex This section contains various settings to control the behavior of the auto generated index. Use this to customize the starting page while having the benefit of not having to specify a manual index. none
metadata:
  author: FOSSASIA
  projectname: Yaydoc
  version: development
  debug: true
  inline_math: true
  autoindex:
    include:
    - README.md
    toc:
      show: true
      heading: Contents
    subproject:
      show: true
      heading: Sub projects
    apidoc:
      show: true
      heading: API Documentation
      javadoc:
        show: true
      swagger:
        show: true
    rss:
      heading: RSS
      url: <rss_url>
    twitter:
      heading: Tweets
      query: fossasia

build

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

build:
  theme: 
    name: sphinx_fossasia_theme
  source: docs
  logo: images/logo.svg
  markdown_flavour: markdown_github
  mock:
    - numpy
    - scipy
  autoapi:
    - language: python
      source: modules
    - language: java
  subproject:
    - url: <URL of Subproject 1>
      source: doc
    - url: <URL of subproject 2>
  github_ribbon:
    position: right
    color: green
  github_button:
    buttons:
      watch: true
      star: true
      issues: true
      fork: true
      follow: true
    show_count: true
    large: true

publish

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

Key Description Default
ghpages It provides a attribute url whose value is written in a CNAME file while publishing to github pages. none
heroku 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 none
publish:
  ghpages:
    url: dev.yaydoc.org
  heroku:
    app_name: yaydoc 

extras

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

Key Description Default
swagger 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. none
javadoc It takes an attribute path and can include javadocs from the repository. none
extras:
  swagger:
    url: http://api.susi.ai/docs/swagger.json
    ui: swagger
  javadoc:
    path: 'src/'