It's said that quality of software is measured by the quality of it's documentation!
As a minimum, the following guides should be produced for each app:
- User Guide
- Configuration Guide
- Deployment Guide
- Developer Guide
Whilst the concept of "word documents on sharepoint sites" is still etched into the skulls of many, there are alternatives available if your firewalls allow. Whilst proprietary office formats and rich text editors are user friendly, they don't fit easily and transparently into source control and continuous integration workflows.
The primary Text Based markup options are MarkDown (md) and reStructuredText (rst). Markdown is easier to learn, whilst RST format is more flexible (can generate PDFs and also provide documentation within code files).
Suitable for small projects, all four guides could be added to a single README file in the root of your repo. Using a tool such as markdown-to-html you can even convert your README into a nicely formatted HTML page as part of your build process.
markdown "$MYPROJECT/README.md" > "$BUILDLOC/deploy/README.html"
This is a great tool for generating a static HTML site where each page can be easily written using MarkDown. This page you are reading was built with MkDocs, as well as the documentation site for Data Controller.
If you want your code in SAS format inside MkDocs markdown, make sure you are using the most recent version (1+) and add the following to your mkdocs.yml file:
theme: name: canBeAnything-UseExistingOneIfThere highlightjs: true hljs_languages: - SAS
Then when you are writing code, just put
sas on the first line of the code block, eg:
```sas data some sas; set formatted nicely; run; ```
With an MkDoks site like this, you can click on any section in the mkdocs site and make edits directly in github. If you find any broken links or typos, or would like to add more sections this site - go right ahead! Your change will be submitted as a PR.
You can even make tips like this! Read on
To create a "tip" like you see above, or the "note" above it, you first need to enable the extension in your
mkdocs.yml like so:
markdown_extensions: - admonition
Then you can write syntax like follows:
!!! note "note title" This is a note !!! warning "warning title" This is a warning !!! error "error title" This is an error !!! tip "tip title" This is a tip
For more info, see docs.
DoxyGen is a commandline tool that can generate a number of output formats, similar to Sphinx. More suitable for documenting code, than generating standalone docs (although it can do that also).
/** @file mv_webout.sas @brief Send data to/from the SAS Viya Job Execution Service @details This macro should be added to the start of each Job Execution Service, **immediately** followed by a call to: %mv_webout(FETCH) This will read all the input data and create same-named SAS datasets in the WORK library. You can then insert your code, and send data back using the following syntax: data some datasets; * make some data ; retain some columns; run; %mv_webout(OPEN) %mv_webout(ARR,some) * Array format, fast, suitable for large tables ; %mv_webout(OBJ,datasets) * Object format, easier to work with ; %mv_webout(CLOSE) @param action Either OPEN, ARR, OBJ or CLOSE @param ds The dataset to send back to the frontend @param _webout= fileref for returning the json @param fref= temp fref @param dslabel= value to use instead of the real name for sending to JSON @param fmt= change to N to strip formats from output <h4> Dependencies </h4> @li mp_jsonout.sas @li mf_getuser.sas @version Viya 3.3 @author Allan Bowe **/
Notice the following:
- file - filename
- brief - a title for the file
- details - a long description, HTML can be embedded. Indent by 4 spaces to format content as code.
- param - a description of each parameter. Keyword parameters have an
- dependencies - not part of the doxygen spec but used by the sasjs-cli to compile macro calls so that each service contains all relevant macros (and no extra macros)
- version - used in the macrocore library to denote the earliest known version in which the code will run
/** @details this is my detailed explanation. This part is indented 2 spaces. %* this is a SAS comment, note the style - avoids the header being closed; %* it is indented 6 spaces (4 spaces from previous non code line); **/
Primarily used for writing in
rst format, sphinx is a very powerful documentation builder, built in python and used for all the official python documentation. The founder of this language went on to launch readthedocs.org a hosting platform for Sphinx-built sites.
Some useful resources:
- Getting started video
- Online RST renderer: https://rst.ninjs.org
- RST Table generator
- Cheatsheet: https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
The good thing about using typescript to build your frontend is that it can auto-generate a lot of documentation as types etc can be inferred from the syntax. The SASjs library is documented this way - adapter.sasjs.io.
More info available here.