This is part of a larger effort to move https://docs.phylum.io/ from
Readme.com to Docusaurus, as a statically generated site. The new site
will host all the documentation, regardless of where the docs originate.
The CLI docs from this repository are included in the
phylum-dev/documentation repository as a git submodule. The format of
the markdown docs has been changed to account for operating in the new
structure and with Docusaurus as the static site generator.
This PR also removes the doc update job from the release workflow.
The release workflow will be updated in a different PR to include a
documentation update trigger step in the Release job. This will look a
lot like the existing trigger steps there. It can't happen until the
documentation repo has a repository_dispatch workflow that allows
for such triggering. In the mean time, any CLI releases that occur before
this change will need to be manually synced with the documentation repo
and deployed from there. Ideally, this will not be needed at all since
the trigger workflow is expected before the next CLI release.
Actions taken include:
Update doc templates to remove unused Readme.com front matter
Remove all doc template files that only existed to specify a category
The sub-categories are removed in favor of simpler command updates
Update gendocs xtask
Remove Readme.com front matter in the default header
Write an H1 header instead of frontmatter as the HEADER
Update links
Update absolute links where the the doc is not included in the site
Update links to be relative where the doc is included in the site
Add a section to the doc_templates/README.md about adding links
Format markdown docs
Update clap_markdown crate
Use H2 headings instead of H3 so as not to "skip" a level
Ensure relative links include the .md extension
Remove frontmatter from all docs and replace it with an H1 header
Update doc_templates
Use H2 headings instead of H3 so as not to "skip" a level
Regenerate all docs with to include changes made here
This is part of a larger effort to move https://docs.phylum.io/ from Readme.com to Docusaurus, as a statically generated site. The new site will host all the documentation, regardless of where the docs originate. The CLI docs from this repository are included in the
phylum-dev/documentation
repository as a git submodule. The format of the markdown docs has been changed to account for operating in the new structure and with Docusaurus as the static site generator.This PR also removes the doc update job from the release workflow. The release workflow will be updated in a different PR to include a documentation update trigger step in the
Release
job. This will look a lot like the existing trigger steps there. It can't happen until thedocumentation
repo has arepository_dispatch
workflow that allows for such triggering. In the mean time, any CLI releases that occur before this change will need to be manually synced with thedocumentation
repo and deployed from there. Ideally, this will not be needed at all since the trigger workflow is expected before the next CLI release.Actions taken include:
gendocs
xtaskdoc_templates/README.md
about adding linksclap_markdown
crate.md
extensiondoc_templates
cargo run -p xtask gendocs
Testing
The changes from this PR can be viewed now at https://docs-stg.phylum.io/.