Configuration

You can configure Docstand by placing rocro.yml at the root of your git repository.

Note: .rocro.yml is also supported. rocro.yml is used preferentially if both exist.

The top level of the YAML configuration starts with docstand:. The second level consists of the tool names that are further mapped to its configuration options.

Note: Check here for tool-wise configuration options.

Default Configuration

docstand:
  <tool>: default

is equivalent to

docstand:
  <tool>: {}

and means that the tool runs with its default configuration.

Example:

docstand:
  javadoc: default

This YAML file enables Docstand to build Javadoc documentation with the default configuration.

Custom Configuration

You can customize the documentation tool by using map notation like below:

docstand:
  <tool>:
    config-file: <string>
    input: <string|list>
    input-dirs: <string|list>
    machine:
      cpu: <string>
    options: <map>

All the fields are optional and not always supported. Please refer to the help page of each tool to see the list of available configuration options.

Note: All the file/directory paths specified in rocro.yml are relative to the root of your Git repository. Absolute paths are also treated as relative paths. i.e. /foo/bar is equivalent to foo/bar.

Field: config-file

config-file specifies the path to the configuration file for the tool and supports only string notation.

docstand:
  <tool>:
    config-file: <path>

Field: input

input specifies the patterns that match the files and directories where you’d like to run the tool. The notation is the same as .dockerignore file, so each pattern can be written in the form similar to the file globs of Unix shells with additional supports of a special wildcard string ** and exceptions starting with !.

input supports string notation and list notation.

[String]
docstand:
  <tool>:
    input: <pattern>
[List]
docstand:
  <tool>:
    input:
      - <pattern1>
      - <pattern2>
      ...

Field: input-dirs

input-dirs specifies the directories under which you'd like to run the tool and supports string and list notation.

[String]
docstand:
  <tool>:
    input-dirs: <path>
[List]
docstand:
  <tool>:
    input-dirs:
      - <path1>
      - <path2>
      ...

Field: machine

machine specifies the computational resource allocated to run the tool. See the format of resource quantity. As of now, you can specify cpu from 250m to 4.

docstand:
  <tool>:
    machine:
      cpu: <quantity>

With regard to the memory (RAM) size, 3.75 GiB are assigned for 1 CPU and the actual size is calculated by multiplying that ratio and the value specified to cpu. For example, 1.875 GiB are assigned for 0.5 (500m) CPU, and 5.625 GiB are assigned for 1.5 CPU.

If machine is not specified, the tool specific default machine will be used. Please refer to help page of each tool for the specification of the default machine.

Note: The default machine for each tool is subject to change.

Field: options

options are essentially the same as command-line flags available for the tool. You can customize the tool by specifying options in the same way you customize it on command-line. Due to security or other reasons, some command-line flags are not supported. Please refer to help page of each tool to see the list of available options.

options supports map notation and list notation.

[Map]

If you do not mind the order in which Docstand specifies options to the tool, options can be declared in mappings of option names and values.

docstand:
  <tool>:
    options:
      <name>: <null|string|list>

For example:

docstand:
  <tool>:
    options:
      # options that do not take any value, such as boolean switches.
      --no-value1:
      --no-value2: null
      --no-value3: []
      # options that take a single value.
      --single-value: value
      # options that take multiple values.
      --multiple-values1: [value1, value2, value3]
      --multiple-values2:
        - value1
        - value2
        - value3
[List]

If you want Docstand to specify options to tools in the strict order, list notation can be used for that purpose.

docstand:
  <tool>:
    options:
      - <string|mapping>
      ...

For example:

docstand:
  <tool>:
    options:
      # (String notation)
      # Unlike mapping notation, options with no values can be declared
      # by putting their names as strings.
      - --no-values
      # (Mapping notation)
      # Each list item can be a mapping of option name and values.
      - --single-value: value
      - --multiple-values: [value1, value2, value3]

With the configuration above, Docstand respects the order of options and specify them to the tool like:

<tool> --no-value --single-value value --multiple-values value1,value2,value3

Furthermore, each list item can also be mappings of option names and values, for example:

docstand:
  <tool>:
    options:
      - --option1-1: value1-1
        --option1-2: value1-2
      - --option2
      - --option3-1: value3-1
        --option3-2: value3-2

With the configuration above, Docstand specifies:

  • --option1-* options prior to --option2
  • --option1-* options in random order among them
  • --option3-* options behind --option2
  • --option3-* options in random order among them

Multiple Tools

You can generate multiple documents from a repository by configuring multiple tools in rocro.yml.

docstand:
  <tool>: ...
  <tool>: ...
  ...

Example:

docstand:
  sphinx:
    config-file: src/python/conf.py
  yard:
    input-files:
      - src/ruby/**/*.rb

This YAML file enables Docstand to build both Sphinx and YARD documents. Sphinx uses src/python/conf.py as the config file and YARD reads src/ruby/**/*.rb as input files.

results matching ""

    No results matching ""