2017-03-26

Write The FAQ ‘n Manual (Part 3)

Automated Documentation in a CI/CD Pipeline for PowerShell Modules with PlatyPS, psake, AppVeyor, GitHub and ReadTheDocs


Part 3: mkdocs & Release Preparations and Pushing the Release

Prepare /header-mkdocs.yml

As explained before, the /header-mkdocs.yml file is used to generate the /mkdocs.yml file which is by ReadTheDocs to create the documentation site.  For the most part you can take the /header-mkdocs.yml file from the AutoDocumentationExample project and modify it for your needs. Just remember that any changes you make to /mkdocs.yml will be overwritten by the build process. Any changes you want to make should be made to the /header-mkdocs.yml instead.

For full documentation on mkdocs.yml, you can read more here: http://www.mkdocs.org/user-guide/configuration/

If you just want to grab, modify, and go, here are some of the lines and what they mean
  • site_name is used to create the name or tile of the documentation site
  • repo_url contains the link to the project repository on GitHub
  • site_author is the Name of the person, persons, company, or organization responsible for the project
  • edit_url is a relative path from the URL defined in Repo_url to edit items. This will be used for construction “edit this page” type links. This is very useful for all of your pages that are not automatically generated by PlatyPS.
  • copyright contains a line about the copyright notices for the project and documentation.
site_name: AutoDocumentsExample - Write The FAQ ‘n Manual
repo_url: https://github.com/markekraus/AutoDocumentsExample
site_author: Mark Kraus
edit_uri: edit/master/docs/
copyright: "AutoDocumentsExample is licensed under the <a href="https://github.com/markekraus/AutoDocumentsExample/raw/master/LICENS">MIT license</a>"


Themes

Themes can be used to change the look and feel of your documentation site. ReadTheDocs comes with 2 built-in themes: mkdocs and readthedocs. You can see the themes and read more about styling at http://www.mkdocs.org/user-guide/styling-your-docs/

For simplicity, you can choose one of the default themes by modifying theme in the /header-mkdocs.yml.
theme: readthedocs

If you want to use someone else’s theme or create your own, you will need to include the theme folder in your project. Then instead of theme, you will need to use theme_dir. I recommend crating a /docs/themes/ folder and then adding the theme folder under there. For example, for a brief period I was using the PSinder theme on the PSMSGraph RedTheDocs site. I did this by placing the PSinder files in /docs/themes/psinder/ and then setting theme_dir to docs/themes/psinder in /header-mkdocs.yml.
theme_dir: docs/themes/psinder

You may want to play around with this a bit before committing to a theme. In my experience the readthedocs theme is the best in terms of working with large numbers of pages, though I’m not exactly thrilled with the aesthetics of the theme. The mkdocs and derivative themes like Cinder and PSinder do not work well with sections that contain a large number of pages. I found that many of my function pages were not selectable in the drop-down menus because they were displayed off screen with no scrolling available. If your project has only a few functions, this might not be an issue.



Additional Pages and Sections

You are not limited to the pages and sections provided here. It is entirely possible to extend this. The idea is that the Functions will be tacked on as individual pages under a Functions section. To add addition pages create them as .md files under /docs/. You can even create more folders under /docs/ to group similar pages or a section. Then just update the pages section in /header-mkdocs.yml

For example, I plan to add an Examples section to PSMSGraph. To do so I will create the /docs/Examples/ folder, add several files (/docs/Examples/example01.md, /docs/Examples/example02.md, etc). and then update /header-mkdocs.yml like so:

pages:
  - Home: index.md
  - Examples:
    - Retrieving Organization Details: Examples/example01.md
    - Uploading a file to OneDrive for Business: Examples/example02.md
    - Adding a Calendar Event: Examples/exampled03.md



Preparing for Release


Assuming you have updated your code, updated the relevant comment based help, and have your /header-mkdocs.yml configured to your liking, you should be ready to publish a release and deploy your module. Before that, you should update your release documentation.

There are two pieces to the release documentation: /RELEASE.md and /docs/ChangeLog.md. /RELEASE.md is intended to function as the Release Notes which document the changes and features added in the current release. /docs/ChangeLog.md is indented to house the current release notes and the release notes for all previous releases. Before you push your release, /RELEASE.md needs to be updated. You do not need to update /docs/ChangeLog.md as the build process will maintain it for you by prepending /RELEASE.md to it.

/RELEASE.md is a markdown file so you use markdown formatting or plain text. It will be included in the ReadTheDocs documentation site. It will also be added to the ReleaseNotes field in the module manifest which ultimately means it will also display in the PowerShell gallery if you are publishing there. Currently, the PowerShell gallery does not format the markdown in the release notes. With these in mind, here are some recommendations for formatting /RELEASE.md
  • Keep to simple formatting so it is still readable as plain text
  • The Version number and date are prepended to the file with a # heading. Use ## for major headers instead of # in your body
  • Use ### for subheadings
  • Consider using just URLs and not trying to create formatted links
  • Consider alternating bullet types for each indentation level:
* First Level
    - Second Level
        + Third Level


The formatting is really up to your preferences. The only hard recommendation I have is the one about the heading levels. The reason for this is that with the version being made the H1 header, the /docs/ChangeLog.md will create better sectioning with all the relevant changes for a specific version nested under the version header as H2 headings.



PowerShell Syntax Highlighting

Unfortunately, ReadTheDocs doesn’t really support PowerShell syntax highlighting for script blocks, but, GitHub does. Also, PowerShell Gallery does not do any formatting. It would probably be best to avoid putting script blocks in your /RELEASE.md so it has a somewhat consistent look across all three services. If you do add script blocks in any of your pages, consider using the following method:

```powershell
$Widgets = Get-Widget 
```

Using that will have the proper syntax highlighting on GitHub and on ReadTheDocs it will appear as a normal preformatted text block. If ReadTheDocs should add PowerShell syntax highlighting in the future, this should be forwards compatible.



Git: Stage, Commit, Push

At this point your code has been updated and your release has been prepped. It is time to work some Git magic. This part should be all too familiar at this point. There is one thing to which I wanted to draw attention and that is the commit message. Our build process can be skipped by including the following string anywhere in your commit message:
  • [ci skip]
  • [skip ci]
  • [skip appveyor]
Note that the square brackets must also be included. This is good for actions such as commits which only update the /README.md or staging the /RELEASE.md before merging code. Using these will result in the commit and push not triggering the build pipeline on AppVeyor and thus your documentation should remain unchanged. However, this will not stop the documentation build on ReadTheDocs. If you edit files in the /docs/ folder and push those changes, ReadTheDocs will build the changes to the documentation even if you include the skip tags in your commit message.

Anyway, assuming you are ready to stage/commit/push:
git add -A
git commit -m 'First Release!'
git push


Go back to Part 2
Continue to Part 4
at
Labels: , , , , , , , , , ,