How to add new documentation

Doc files are all located in the docs folder at root level in the repository. Each library (Core, Content Services, etc) has its own subfolder within the docs folder. The content of all doc files is written in GitHub flavored Markdown.

Use the following steps to prepare docs for submission to ADF:

1. The easiest way to create a new doc file is with the Angular CLI schematic generator, located in the tools folder (instructions are given in the README file for the schematic). Alternatively, you can copy an existing file and rename it. The .md file should be named the same way as the .ts file (so "xxx.component.ts" should be documented in "xxx.component.md"). You should add the file to the appropriate library subfolder within the docs folder (core, content-services, etc).

2. Follow the general structure of an existing similar component, service, etc. In particular:

   • The text should have only one top-level heading for the title. This should be like the file name but with titlecase and with the dashes replaced by spaces. So "my-feature.component.md" would have "My Feature Component" as its title.
   • The first paragraph should be a one-line description of what the component does. This description will appear in index lists and so it is important to keep it short and snappy.
   • Use the existing level 2 headings (Basic Usage, Details, See Also, etc) but don't add any new ones. Describe the component using level 3 sections within the Details section.

   The scaffold doc file generated by the schematic has placeholders that help you to follow the correct structure.

3. (Optional) Rebuild the docs (see Rebuilding the docs below) to add the new file to the index and generate the property tables, etc.

4. Commit, push, etc.

Rebuilding the docs

The index pages are built using a script and so any new doc files you add won't appear in the index until the script is run. This gets done regularly but if you want your new component to be listed immediately then you should rebuild the index yourself. From the command line, use cd to set the working directory to lib and then type:

npm run docbuild -- docs/<lib-folder>/<new-doc-file>

When the script has finished, you should see your new component listed in docs/README.md. If you see "not currently documented" in the description field then check that the doc file has the correct name format, as described above.

As well as building the index pages, the "docbuild" script will generate property and/or method tables as appropriate for the class and populate these with JSDocs, if you have added them in the sources.

Note that if you run

npm run docbuild

...without the path parameter then all doc files will be updated.

Enhance Markdown File

If you add new properties and you want e enhance Markdown file you can use

npm run docbuild -- -p enhance docs/<lib-folder>/<doc-file>

Adding metadata

We use metadata in the doc files to track several useful items of information. The metadata appears in a section at the top of the Markdown file, surrounded by "---" markers:

---
Added: v2.0.0
Status: Active
---

# Accordion Component

Creates a collapsible accordion menu.
...

New items of metadata get added from time to time but the most important items are the ones in the example above:

• Added: This tracks the version where the component was added and is used to generate the version index page. The version should be a string of the form "vX.X.X" reflecting the semver numbers.
• Status: This tracks the availability status of the component. If you omit this field then the status will be assumed to be "Active", which indicates that the component is suitable for normal use. Two other status values are also used. "Experimental" means that the component is available only temporarily or not fully tested and developed yet. "Deprecated" means that the component is still available but is obsolete and likely to be removed in a future version.