Skip to content

Latest commit

 

History

History
215 lines (183 loc) · 16.9 KB

CONTRIBUTING.md

File metadata and controls

215 lines (183 loc) · 16.9 KB
Raw

Contributing to the documentation

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

There are several ways to contribute to this project:

  1. Filing issues
  2. Adding new languages
  3. Adding new features
  4. Adding new engines
  5. Improving the documentation
  6. Changing documentation templates

Filing Issues

Issues can be filed via the GitHub Issues tab.

Adding New Languages

Using hygen

  1. Run npm run g:language and follow the prompts.
  2. Make any changes necessary to src/languages/<language-id>.md, where language-id is unique language identifier.

Adding an language manually

To add a new language:

  1. Copy src/languages/.template.md to a new file named src/languages/<language-id>.md, where language-id is a unique language identifier.

  2. Edit src/languages/<language-id>.md and change the following fields in the YAML frontmatter:

    NOTE: The ### YamlMime:Language comment at the top of the frontmatter is required for validation and inclusion.

    NOTE: The YAML schema for a language can be found in scripts/schemas/yaml.json (under definitions/Language).

    1. language — (required) A unique identifier for the language. This should consist of lowercase alpha-numeric characters and . or - separators.
    2. name — (required) The human readable name of the language.
    3. reference — (required) A URL linking to more information about the language (such as an official documentation page).
    4. description — (optional) A markdown description for the language. To make it easier to use markdown formatting, you can use a YAML alias to point to markdown content:
      • *content — An alias to the entire markdown document (excluding frontmatter).
      • *content.description — An alias to the first # description header in the markdown document.
    5. see_also — (optional) Either a markdown string or a list of link definitions pointing to other content: 
      see_also:
- c                            # A link to another language by its identifier
- name: C++                    # A link to another programming language by its expanded form
  language: cpp
- name: Oniguruma              # A link to an engine
  engine: oniguruma
- name: Wildcards              # A link to a feature
  feature: wildcard
- name: External Link          # A link to an external source
  href: https://example.com
    6. links — (optional) Markdown link references to add to the end of the document to make repeated [Link Name] references easier in markdown: 
      - name: Foo                    # Use in markdown as [Foo] or [Foo][]
  href: https://example.com
    7. content — (optional) Overrides the generated content for the language and uses the supplied markdown instead. This isn't recommended unless specific custom rendering is required.

  3. Edit src/languages/language-toc.yml and add an entry for the new language identifier to the list.

Adding New Features

Using hygen

  1. Run npm run g:feature and follow the prompts.
  2. Make any changes necessary to src/features/<feature-id>.md, where feature-id is unique feature identifier.

Adding an feature manually

To add a new feature:

  1. Copy src/features/.template.md to a new file named src/features/<feature-id>.md, where feature-id is a unique feature identifier.

  2. Edit src/features/<feature-id>.md and change the following fields in the YAML frontmatter:

    NOTE: The ### YamlMime:Feature comment at the top of the frontmatter is required for validation and inclusion.

    NOTE: The YAML schema for a feature can be found in scripts/schemas/yaml.json (under definitions/Feature).

    1. feature — (required) A unique identifier for the feature. This should consist of lowercase alpha-numeric characters and . or - separators.
    2. name — (required) The human readable name of the feature.
    3. reference — (required) A URL linking to more information about the feature (such as an official documentation page).
    4. aliases — (optional) A list of other names by which this feature is known. These are added as link references at the bottom of the markdown document to make repeated [Link Name] references easier in markdown. For example: 
      name: Character Classes
aliases:
- Character Class
    5. description — (optional) A markdown description for the feature. To make it easier to use markdown formatting, you can use a YAML alias to point to markdown content:
      • *content — An alias to the entire markdown document (excluding frontmatter).
      • *content.description — An alias to the first # description header in the markdown document.
    6. syntax — (optional) A markdown string describing a common or well-known syntax of the feature across multiple engines. To make it easier to use markdown formatting, you can use a YAML alias to point to markdown content:
      • *content — An alias to the entire markdown document (excluding frontmatter).
      • *content.syntax — An alias to the first # syntax header in the markdown document.
    7. example — (optional) A markdown string describing an example usage of the feature across multiple engines. To make it easier to use markdown formatting, you can use a YAML alias to point to markdown content:
      • *content — An alias to the entire markdown document (excluding frontmatter).
      • *content.example — An alias to the first # example header in the markdown document.
    8. see_also — (optional) Either a markdown string or a list of link definitions pointing to other content: 
      see_also:
- character-classes            # A link to another feature by its identifier
- name: Wildcards              # A link to another feature by its expanded form
  feature: wildcard
- name: C++                    # A link to a programming language
  language: cpp
- name: Oniguruma              # A link to an engine
  engine: oniguruma
- name: External Link          # A link to an external source
  href: https://example.com
    9. links — (optional) Markdown link references to add to the end of the document to make repeated [Link Name] references easier in markdown: 
      - name: Foo                    # Use in markdown as [Foo] or [Foo][]
  href: https://example.com
    10. content — (optional) Overrides the generated content for the feature and uses the supplied markdown instead. This isn't recommended unless specific custom rendering is required.

  3. Copy src/engines/default/features/.template.md to a new file named src/engines/default/features/<feature-id>.md where feature-id matches the feature identifer above.

    NOTE: The default engine is used to define general-purpose fallback values for features in actual engines.

  4. Edit src/engines/default/features/<feature-id>.md and change the following fields in the YAML frontmatter:

    NOTE: The ### YamlMime:EngineFeature comment at the top of the frontmatter is required for validation and inclusion.

    NOTE: The YAML schema for a feature can be found in scripts/schemas/yaml.json (under definitions/EngineFeature).

    1. feature — (required) This much match the feature identifier above.
    2. supported — (optional) Set to true if this feature is generally supported across.
    3. description, syntax, example — (optional) These provide overrides for the same fields above, but can be used as the default value for the feature when referenced by an engine.

  5. Edit src/features/feature-toc.yml and add an entry for the new feature identifier to the list.

Adding New Engines

To add a new engine:

Using hygen

  1. Run npm run g:engine and follow the prompts.
  2. Make any changes necessary to src/engines/<engine-id>/engine.md and src/engines/<engine-id>/features/*.md, where engine-id is unique engine identifier.

Adding an engine manually

  1. Copy the src/engines/.template directory to a folder named src/engines/<engine-id>, where engine-id is unique engine identifier.
  2. In the new engine folder:

    1. Edit engine.md and change the following fields in the YAML frontmatter:

      NOTE: The ### YamlMime:Engine comment at the top of the frontmatter is required for validation and inclusion.

      NOTE: The YAML schema for an engine can be found in scripts/schemas/yaml.json (under definitions/Engine).

      1. engine — (required) A unique identifier for the engine. This should consist of lowercase alpha-numeric characters and . or - separators.
      2. name — (required) The human readable name of the engine.
      3. reference — (required) A URL linking to more information about the engine (such as an official documentation page).
      4. languages — (optional) An array of languages where the engine can generally be used. Each entry should be a language identifier.
      5. description — (optional) A markdown description for the engine. To make it easier to use markdown formatting, you can use a YAML alias to point to markdown content:
        • *content — An alias to the entire markdown document (excluding frontmatter).
        • *content.description — An alias to the first # description header in the markdown document.
      6. see_also — (optional) Either a markdown string or a list of link definitions pointing to other content: 
        see_also:
- pcre                         # A link to another engine by its identifier
- name: Oniguruma              # A link to another engine by its expanded form
  engine: oniguruma
- name: Wildcards              # A link to a feature
  feature: wildcard
- name: C++                    # A link to a programming language
  language: cpp
- name: External Link          # A link to an external source
  href: https://example.com
      7. links — (optional) Markdown link references to add to the end of the document to make repeated [Link Name] references easier in markdown: 
        - name: Foo                    # Use in markdown as [Foo] or [Foo][]
  href: https://example.com
      8. content — (optional) Overrides the generated content for the engine and uses the supplied markdown instead. This isn't recommended unless specific custom rendering is required.

    2. In the features subfolder, edit each feature markdown file to specify feature support for the engine:

      NOTE: The ### YamlMime:EngineFeature comment at the top of the frontmatter is required for validation and inclusion.

      NOTE: The YAML schema for an engine feature can be found in scripts/schemas/yaml.json (under definitions/EngineFeature).

      1. engine — (required) A unique identifier for the engine. This should consist of lowercase alpha-numeric characters and . or - separators and should match the engine identifier of the supported engine.
      2. feature — (required) A unique identifier for the feature. This should consist of lowercase alpha-numeric characters and . or - separators and should match the feature identifier of the supported feature.
      3. reference — (required) A URL linking to more information about the feature (such as an official documentation page).
      4. supported — (required) Either true to indicate the feature is supported, or false to indicat the feature is not supported.
      5. description — (optional) A markdown description for the engine. If not supplied, a fallback description is used (either from src/engines/default/<feature>.md or from src/features/<feature>.md). To make it easier to use markdown formatting, you can use a YAML alias to point to markdown content:
        • *content — An alias to the entire markdown document (excluding frontmatter).
        • *content.description — An alias to the first # description header in the markdown document.
      6. syntax — (optional) A markdown string describing the syntax of the feature for the engine. If not supplied, a fallback syntax is used (either from src/engines/default/<feature>.md or from src/features/<feature>.md). To make it easier to use markdown formatting, you can use a YAML alias to point to markdown content:
        • *content — An alias to the entire markdown document (excluding frontmatter).
        • *content.syntax — An alias to the first # syntax header in the markdown document.
      7. example — (optional) A markdown string describing an example usage of the feature for the engine. If not supplied, a fallback example is used (either from src/engines/default/<feature>.md or from src/features/<feature>.md). To make it easier to use markdown formatting, you can use a YAML alias to point to markdown content:
        • *content — An alias to the entire markdown document (excluding frontmatter).
        • *content.example — An alias to the first # example header in the markdown document.
      8. see_also — (optional) Either a markdown string or a list of link definitions pointing to other content: 
        see_also:
- pcre                         # A link to another engine by its identifier
- name: Oniguruma              # A link to another engine by its expanded form
  engine: oniguruma
- name: Wildcards              # A link to a feature
  feature: wildcard
- name: C++                    # A link to a programming language
  language: cpp
- name: External Link          # A link to an external source
  href: https://example.com
      9. links — (optional) Markdown link references to add to the end of the document to make repeated [Link Name] references easier in markdown: 
        - name: Foo                    # Use in markdown as [Foo] or [Foo][]
  href: https://example.com
      10. content — (optional) Overrides the generated content for the engine and uses the supplied markdown instead. This isn't recommended unless specific custom rendering is required.
  3. Edit src/engines/engine-toc.yml and add an entry for the new engine identifier to the list.

Improving the Documentation

While browsing the generated documentation at https://rbuckton.github.io/regexp-features/, you will often see links to "Improve this Article" or "Improve this Section". Clicking on one of those links will take you to a file edit page on https://github.com/rbuckton/regexp-features allowing you to make changes and easily create a PR.

Changing Documentation Templates

This project uses handlebars.js to generate documentation. The template files used to generate the documentation can be found in scripts/templates.