hardis:doc:project2markdown

Description

Generates a markdown documentation from a SFDX project

Package.xml files
Source Packages
sfdx-hardis configuration
Installed packages

Can work on any sfdx project, no need for it to be a sfdx-hardis flavored one.

Generates markdown files will be written in docs folder (except README.md where a link to doc index is added)

To read Flow documentations if your markdown reader doesn't handle MermaidJS syntax, this command could require @mermaid-js/mermaid-cli

Run npm install @mermaid-js/mermaid-cli --global if puppeteer works in your environment
It can also be run as a docker image

Both modes will be tried by default, but you can also force one of them by defining environment variable MERMAID_MODES=docker or MERMAID_MODES=cli

sfdx-hardis docker image is alpine-based and does not succeed to run mermaid/puppeteer: if you can help, please submit a PR !

If Flow history doc always display a single state, you probably need to update your workflow configuration:

on Gitlab: Env variable GIT_FETCH_EXTRA_FLAGS: --depth 10000
on GitHub: fetch-depth: 0
on Azure: fetchDepth: "0"
on Bitbucket: step: clone: depth: full

If it is a sfdx-hardis CI/CD project, a diagram of the branches and orgs strategy will be generated.

If AI integration is configured, documentation will contain a summary of the Flow.

If you have a complex strategy, you might need to input property mergeTargets in branch-scoped sfdx-hardis.yml file to have a correct diagram.

Doc HTML Pages

To read the documentation as HTML pages, run the following code (you need Python on your computer)

pip install mkdocs-material mdx_truly_sane_lists || python -m pip install mkdocs-material mdx_truly_sane_lists || py -m pip install mkdocs-material mdx_truly_sane_lists
mkdocs serve || python -m mkdocs serve || py -m mkdocs serve

To just generate HTML pages that you can host anywhere, run mkdocs build || python -m mkdocs build || py -m mkdocs build

Parameters

Name	Type	Description
debug -d	boolean	Activate debug mode (more logs)
diff-only	boolean	Generate documentation only for changed files (used for monitoring)
flags-dir	option	undefined
json	boolean	Format output as json.
skipauth	boolean	Skip authentication check when a default username is required
target-org -o	option	undefined
websocket	option	Websocket host:port for VsCode SFDX Hardis UI integration
with-history	boolean	Generate a markdown file with the history diff of the Flow

Examples

$ sf hardis:doc:project2markdown

$ sf hardis:doc:project2markdown --with-history