Muokkaa

Jaa

Overwriting help with the ALDoc tool

  • Artikkeli

The ALDoc tool generates reference documentation for first party apps for Business Central. This documentation is based on comments and syntactical information in the source code. Learn more in Generating help with the ALDoc tool.

Some areas of autogenerated content work as they are, showing syntactical information, code comments, and overall application structure based on the input .app file(s). Some areas of the autogenerated content might need more information, guidance, or remarks to add extra value for the reader of the documentation. The ALDoc tool supports what is referred to as overwrites of the autogenerated articles. An overwrite is defined as a new file with content that is injected into autogenerated content. The overwrite functionality injects one or more sections at the top of an autogenerated article; it doesn't overwrite that content if the ALDoc tool is run again to pick up code changes in the .app file.

Prerequisites

The overwrite functionality is part of the DocFx support. To enable overwrites, make sure that you have the required prerequisites in place. Learn more in Generating help with the ALDoc tool.

Overwriting content of an autogenerated article

To get started, you need to inspect the docfx.json file to ensure that the settings are as you want them to be.

  1. Go to the top folder level of the autogenerated content.
  2. Locate and open the docfx.json file to inspect the content. Check that there's a setting similar to the following: "overwrite": "override_file/**.md".
  3. Change the location folder of the overwrite file if needed, but keep the latter part **.md.
  4. Save the docfx.json file, if you have made changes.

Next, you create an .md file with the content to inject as an overwrite.

  1. Create a folder for overwrite files at the location specified in the docfx.json file. The folder must be named what you specified in the docfx.json file.
  2. In the folder, create an .md file, which contains the injected content.

    Note

    The relation between an autogenerated content file and the overwrite is 1:1. A best practice is to name the file according to the file it overwrites.

  3. In the folder of the autogenerated content, locate the article (.yml format) that you want to overwrite content for.
  4. Copy the uid metadata tag of that article, similar to the following format uid: "O:Codeunit::Auto_Format".
  5. Edit the .md file by inserting yaml metadata tags to reference the content file that you want to overwrite. For example: 
    ---
uid: "O:Codeunit::Auto_Format"
summary: Exposes functionality to format the appearance of decimal data types in fields of a table, report, or page.
---
## Introduction
The Auto Format codeunit provides methods for formatting the appearance of decimal data types in fields on tables, reports, and pages.
  6. Save the .md file when you're done.
  7. Next, build the help site again with the equivalent command of: 
    docfx build ./{path-to-generated-content}/docfx.json -s

Now, go to the help site that your reference documentation builds to and check that the reference article has the expected injected text at the beginning of the article.

Generating help with the ALDoc tool