4.5 KiB

Raw Blame History

Write documentation

The NTFSSecurity documentation is written in Markdown and built into a website with MkDocs. This page explains how the documentation is organized and how to change it.

Documentation structure

Path	Content
`Docs/index.md`	Home page with features, requirements, and the cmdlet list
`Docs/Concepts.md`	Background on security descriptors, rights, inheritance, and privileges
`Docs/Examples.md`	Task-oriented examples
`Docs/Cmdlets/*.md`	One reference page per cmdlet, in platyPS format
`Docs/Contributing.md`, `Docs/Contributing/*.md`	This contributor guide
`mkdocs.yml`	Site settings and navigation
`.readthedocs.yml`	Build settings for Read the Docs
`README.md`	Front page of the GitHub repository

When you add a page, add it to the nav section of mkdocs.yml.

Markdown editors

Any text editor works. These editors have good Markdown support:

Visual Studio Code with the markdownlint extension
Sublime Text

To get started with Markdown, see How to use Markdown for writing Docs. Don't use hard tabs. For the rules that apply to this repository, see Markdown and platyPS specifics.

Update the cmdlet reference

The pages in Docs/Cmdlets are platyPS Markdown files. platyPS reads the parameter metadata from the module, so the syntax and the parameter details always match the code. You write the synopsis, the description, the parameter descriptions, the examples, and the notes.

When a cmdlet changes, build the module, import the build output, and update the pages in Windows PowerShell 5.1. A Release build writes the module to NTFSSecurity\bin\Release; the before_build and build_script steps in appveyor.yml show the commands that the CI build uses:

Install-Module -Name platyPS -RequiredVersion 0.14.2
Import-Module -Name .\NTFSSecurity\bin\Release\NTFSSecurity.psd1
Update-MarkdownHelp -Path .\Docs\Cmdlets

Update-MarkdownHelp updates the syntax and the parameter metadata and keeps the text that you wrote. Fill in the description of every new parameter.

Use Windows PowerShell 5.1 for platyPS. In PowerShell 7.4 and later, platyPS 0.14.2 adds the -ProgressAction common parameter to every page.

For a new cmdlet, create the page, replace every placeholder in it, and add the page to mkdocs.yml. Replace Get-NTFSExample with the name of the new cmdlet:

New-MarkdownHelp -Command Get-NTFSExample -OutputFolder .\Docs\Cmdlets

To check that the pages can be converted to the help file that Get-Help reads, run New-ExternalHelp:

New-ExternalHelp -Path .\Docs\Cmdlets -OutputPath $env:TEMP\NTFSSecurityHelp

Preview the website

MkDocs needs Python. Install the MkDocs version that the site is built with and start the preview server:

pip install -r Docs/requirements.txt
mkdocs serve

Open http://127.0.0.1:8000 in a browser. The preview reloads when you save a file. Run mkdocs build --strict to find broken links and pages that are missing from the navigation.

Check your change

Before you open a pull request, check the following:

No page in Docs/Cmdlets contains a {{ ... }} placeholder.
Update-MarkdownHelp doesn't change any page in Docs/Cmdlets. The build defined in appveyor.yml runs the same check.
All links work. The build checks them with Get-MarkdownLink from the MarkdownLinkCheck module:
```
Get-MarkdownLink -Path .\Docs -BrokenOnly
```
Every example works. Test examples in a test folder, never on production data.

Create new topics

Before you write a new topic, check the issues labeled Documentation or Help Wanted to make sure nobody else is working on it. If nobody is, open an issue that describes the topic and say that you're working on it. Then follow the workflow for larger changes in Get started.

Next steps

Read the Style guide.

4.5 KiB Raw Blame History