PaloAltoNetworks / PaloAltoNetworks/docusaurus-openapi-docs

What are the variables in api.mustache template?

Open
#900 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
Dominant language
TypeScript
Stars
1.1k
Forks
315
Avg merge
7d 5h
Merged PRs (30d)
7

Description

Documentation link

Missing documentation for https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/6c12cd7fcd74e4fe8c8b02137ee1077daad136ac/demo/api.mustache.

Describe the problem

Every time I regenerate API docs, the api: variable keep changing in all the generated mdx files and it's usually a long string of characters. This is very distracting for code reviews and in git history. I can't find documentation on what it actually is. I also can't find documentation for all other variables in that api.mustache template, which makes it very hard for me to customize the template.

Suggested fix

  1. Add documentation to explain what the api: variable is and how we can configure the project such that it doesn't have to change every time we regenerate the mdx files.
  2. Add documentation to explain what each of the variables in api.mustache template.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with demo/api.mustache at the linked revision and compare its variables with the generated MDX files. Trace the source of the changing api: value and the project configuration that controls it. Done means documentation explains that value, how to keep it stable, and every variable available in the template.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, react, typescript
Domain
api, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.