Configuration normalization for Kit::Doc.

opts is a hash that can contain the following keys:

• :project_path - Absolute path of the project home directory.

• :git_project_path - Absolute path of the project git home directory. It will sometimes be different from :project_path in a multi-project setup. This is necessary when using all_versions tasks, that will checkout different versions of the project.

• :project - Project name. Autofilled from gemspec if :gemspec_name is set.

• :current_version - Semver name of the current version. Example: "0.1.0". Defaults to dev (this is the most common usage: previewing new documentation).

• :source_ref - The branch/commit/tag used for source link inference. Autogenerated if nil. If :git_project_path is set, the current branch be used if found, last commit otherwise. Defaults to master otherwise.

• :current_version_display - Version that will be displayed. Autogenerated if nil: add v in front of :version values that start with an integer. Example: version: '0.1.0' would lead to version_display: 'v0.1.0'.

• :all_versions - List of version & source_ref to be used for all_versions tasks and javascript versionNodes. Example: [{ version: 'edge', source_ref: 'master' }, { version: 'v0.0.1', source_ref: 'v0.0.1' }] If a string is given, assume it is the path to a VERSIONS file that will be loaded.

• :output_dir_all_versions - Container directory for various versioned generated docs. Defaults to "#{ project_path }/docs/dist". If a relative path is provided it will be auto-expanded to an absolute path.

• :output_dir_current_version - Output directory for the generated docs. If a relative path is provided it will be auto-expanded to an absolute path. Auto-generated from :output_dir_all_versions and :current_version if nil.

• :documentation_url - The address of the generated documentation. Autofilled from gemspec if :gemspec_name is set.

• :source_url - The address of code source. Autofilled from gemspec if :gemspec_name is set.

• :url_mode - Defaults to :local. If :local, :documentation_url is set to file:// URI scheme. Useful for browsing dev documentation. (TODO: apply to source_url also when we find a good way to preview code locally. view-source URI scheme does not have syntax highligthing or line number anchors.)

• :files_modules - List of files to generate documentation from. See Kit::Doc::Services::Tasks::Helpers.resolve_files for a helper to express that list in a terser way.

• :groups_for_modules - See the "Groups" section

• :files_extras - List of Markdown files to add to the documentation. See Kit::Doc::Services::Tasks::Helpers.resolve_files for a helper to express that list in a terser way.

• :groups_for_extras - See the "Groups" section

• :extras_section_name - String that defines the section title of the additional Markdown pages. Defaults to "Guides".

• :logo - Path to the image logo of the project.

• :authors - List of authors for the generated docs. Autofilled from gemspec if :gemspec_name is set.

• :markdown_variables - Hash of values available in Markdown pre-processing. See Kit::Doc::Services::MarkdownPreprocessor.

• :assets - List of paths to files or directories that will be copied as is to the "assets" directory in the output path.

• :main_redirect_url - Path to the default page for the documentation. The top level index.html for the :current_version documentation will redirect there. Defaults to "api_reference.html".

Groups

The output sidebar content can be organized in groups. This is done via the :groups_for_extras and :groups_for_modules. For example, imagine you are storing extra guides in your documentation which are organized per directory. In the extras section you have:

extras: [
  "guides/introduction/foo.md",
  "guides/introduction/bar.md",
  # ...
  "guides/advanced/baz.md",
  "guides/advanced/bat.md",
],

You can have those grouped as follows:

groups_for_extras: {
  'Introduction' => [%r{guides/introduction/.?}],
  'Advanced'     => [%r{guides/advanced/.?}],
},

Similar can be done for modules:

groups_for_modules: {
  # The "empty" group is where modules not included in another group go.
  ''          => [
    {
      # Here we define the ones we want to hide from that category.
      inclusion: %r{^(Kit|Kit::Doc|Kit::Doc::Services)$},
      display:   false,
    },
  ],
  'Services'  => [
    {
      # Match on the fully qualified name.
      inclusion:     %r{^Kit::Doc::Services::.*},
      # A callable that will receive and modify the display name of the module.
      display_title: ->(name) { name.split('::')[-1] },
      # A callable that will the name of the module and return a list of css classes to be applied.
      # This can for instance be used to add padding.
      css_classes:   ->(name) do
        size = name.gsub('hide', 'Kit::Doc::Services::').scan('::').size
        ["#{ (size > 0) ? "sidebar-pl-#{ size }" : '' }"]
      end,
    },
  ],

Generate a versioned source link for a given source_ref & path & line number.

Attempt to guess the most accurate git source_ref.

If git_project_path is set, it will attempt to find the current branch first, then the last commit. Otherwise, defaults to master.

Load a gemspec file data.

Parse a VERSIONS file.

It contains all versions we want to generate documentation for.

Expected format

On each line:

version[:source_ref]`

• version - The name of the version.

• source_ref - The branch/commit/tag used for source link inference. Defaults to version if not specified.

Example

edge:master
v0.0.1

This Service currently acts as a singleton to reference the current config for Yard rake tasks.

This is obviously not ideal / thread safe, but it is only used for tooling, so it does not matter.

A regex that match semantic versioning (semver) versions.

Note that this is a more permissive version to match semver inside strings and allow for leading v.

References:

• https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string