From 974479831d5f1622bc9be76bf9821f21820820a0 Mon Sep 17 00:00:00 2001 From: Dimple Kuriakose Date: Mon, 14 Oct 2024 11:35:22 +0530 Subject: [PATCH] Test markdown linting - 1 --- .github/workflows/markdown-style-checks.yml | 21 ++ contributing-myst.md | 183 ++++++++++++++ doc-cheat-sheet-myst.md | 261 ++++++++++++++++++++ index-myst.md | 74 ++++++ test-md.md | 7 + 5 files changed, 546 insertions(+) create mode 100644 .github/workflows/markdown-style-checks.yml create mode 100644 contributing-myst.md create mode 100644 doc-cheat-sheet-myst.md create mode 100644 index-myst.md create mode 100644 test-md.md diff --git a/.github/workflows/markdown-style-checks.yml b/.github/workflows/markdown-style-checks.yml new file mode 100644 index 00000000..c989b563 --- /dev/null +++ b/.github/workflows/markdown-style-checks.yml @@ -0,0 +1,21 @@ +name: "Linter for Markdown" + +on: [push, pull_request] + +jobs: + markdown-lint: + runs-on: ubuntu-22.04 + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: tj-actions/changed-files@v44 + id: changed-markdown-files + with: + files: | + *.md + - uses: DavidAnson/markdownlint-cli2-action@v16 + if: steps.changed-markdown-files.outputs.any_changed == 'true' + with: + globs: ${{ steps.changed-markdown-files.outputs.all_changed_files }} + separator: "," \ No newline at end of file diff --git a/contributing-myst.md b/contributing-myst.md new file mode 100644 index 00000000..cb664bb2 --- /dev/null +++ b/contributing-myst.md @@ -0,0 +1,183 @@ +--- +orphan: true +--- + + + + +# How to contribute + +We believe that everyone has something valuable to contribute, whether you're a coder, a writer, or a tester. Here's how and why you can get involved: + +- **Why join us?** Work with like-minded people, develop your skills, connect with diverse professionals, and make a difference. +- **What do you get?** Personal growth, recognition for your contributions, early access to new features, and the joy of seeing your work appreciated. +- **Start early, start easy**: Dive into code contributions, improve documentation, or be among the first testers. Your presence matters, regardless of experience or the size of your contribution. + +The guidelines below will help keep your contributions effective and meaningful. + +## Code of conduct + +When contributing, you must abide by the [Ubuntu Code of Conduct](https://ubuntu.com/community/ethos/code-of-conduct). + +## Licence and copyright + + + +By default, all contributions to ACME are made under the AGPLv3 licence. See the [licence](https://github.com/canonical/ACME/blob/main/COPYING) in the ACME GitHub repository for details. + +All contributors must sign the [Canonical contributor licence agreement](https://ubuntu.com/legal/contributors), which grants Canonical permission to use the contributions. The author of a change remains the copyright owner of their code (no copyright assignment occurs). + +## Releases and versions + + + +ACME uses [semantic versioning](https://semver.org/); major releases occur once or twice a year. + +The release notes can be found TODO: [here](https://example.com). + +## Environment setup + + + +To work on the project, you need the following prerequisites: + +- [TODO: Prerequisite 1](http://example.com) +- [TODO: Prerequisite 2](http://example.com) + +To install and configure these tools: + +```bash +TODO: prerequisite command 1 +TODO: prerequisite command 2 +``` + +## Submissions + + + +If you want to address an issue or a bug in ACME, notify in advance the people involved to avoid confusion; also, reference the issue or bug number when you submit the changes. + +- Fork [our GitHub repository](https://github.com/canonical/ACME) and add the changes to your fork, properly structuring your commits, providing detailed commit messages, and signing your commits. + +- Make sure the updated project builds and runs without warnings or errors; this includes linting, documentation, code, and tests. + +- Submit the changes as a [pull request (PR)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork). + +Your changes will be reviewed in due time; if approved, they will eventually be merged. + +### Describing pull requests + + + +To be properly considered, reviewed, and merged, your pull request must provide the following details: + +- **Title**: Summarise the change in a short, descriptive title. +- **Description**: Explain the problem that your pull request solves. Mention any new features, bug fixes, or refactoring. +- **Relevant issues**: Reference any [related issues, pull requests, and repositories](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls). +- **Testing**: Explain whether new or updated tests are included. +- **Reversibility**: If you propose decisions that may be costly to reverse, list the reasons and suggest steps to reverse the changes if necessary. + +### Commit structure and messages + + + +Use separate commits for each logical change, and for changes to different components. Prefix your commit messages with the names of components they affect, using the code tree structure. For example, start a commit that updates the ACME service with `ACME/service:`. + +Use [conventional commits](https://www.conventionalcommits.org/) to ensure consistency across the project: + +```none +Ensure correct permissions and ownership for the content mounts + +* Work around an ACME issue regarding empty dirs: https://github.com/canonical/ACME/issues/12345 + +* Ensure the source directory is owned by the user running a container. + +Links: +- ... +- ... +``` + +Such structure makes it easier to review contributions and simplifies porting fixes to other branches. + +### Signing commits + + + +To improve contribution tracking, we use the developer certificate of origin ([DCO 1.1](https://developercertificate.org/)) and require a "sign-off" for any changes going into each branch. + +The sign-off is a simple line at the end of the commit message certifying that you wrote it or have the right to commit it as an open-source contribution. + +To sign off on a commit, use the `--signoff` option in `git commit`. + +## Code + +### Formatting and linting + + + +ACME relies on these formatting and linting tools: + +- [TODO: Tool 1](http://example.com) +- [TODO: Tool 2](http://example.com) + +To configure and run them: + +```bash +TODO: lint command 1 +TODO: lint command 2 +``` + +### Structure + +- **Check linked code elements**: Ensure coupled code elements, files, and directories are adjacent. For instance, store test data close to the corresponding test code. +- **Group variable declaration and initialisation**: Declare and initialise variables together to improve code organisation and readability. +- **Split large expressions**: Break down large expressions into smaller self-explanatory parts. Use multiple variables where appropriate to make the code more understandable and choose names that reflect their purpose. +- **Use blank lines for logical separation**: Insert a blank line between two logically separate sections of code to improve its structure and readability. +- **Avoid nested conditions**: Avoid nesting conditions to improve readability and maintainability. +- **Remove dead code and redundant comments**: Drop unused or obsolete code and comments to promote a cleaner code base and reduce confusion. +- **Normalise symmetries**: Treat identical operations consistently, using a uniform approach to improve consistency and readability. + +### Best practices + + + +## Tests + + + +All code contributions must include tests. + +To run the tests locally before submitting your changes: + +```bash +TODO: test command 1 +TODO: test command 2 +``` + +## Documentation + +ACME's documentation is stored in the `DOCDIR` directory of the repository. It is based on the [Canonical starter pack](https://canonical-starter-pack.readthedocs-hosted.com/latest/) and hosted on [Read the Docs](https://about.readthedocs.com/). + +For general guidance, refer to the [starter pack guide](https://canonical-starter-pack.readthedocs-hosted.com/latest/). + +For syntax help and guidelines, refer to the [Canonical style guides](https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/#style-guides). + +In structuring, the documentation employs the [Diátaxis](https://diataxis.fr/) approach. + +To run the documentation locally before submitting your changes: + +```bash +make run +``` + +### Automatic checks + +GitHub runs automatic checks on the documentation to verify spelling, validate links, and suggest inclusive language. + +You can (and should) run the same checks locally: + +```bash +make spelling +make linkcheck +make woke +``` diff --git a/doc-cheat-sheet-myst.md b/doc-cheat-sheet-myst.md new file mode 100644 index 00000000..6257c9db --- /dev/null +++ b/doc-cheat-sheet-myst.md @@ -0,0 +1,261 @@ +--- +orphan: true +myst: + substitutions: + reuse_key: "This is **included** text." + advanced_reuse_key: "This is a substitution that includes a code block: + ``` + code block + ```" +--- + + + +(cheat-sheet-myst)= +# Markdown/MyST cheat sheet + + + +This file contains the syntax for commonly used Markdown and MyST markup. +Open it in your text editor to quickly copy and paste the markup you need. + +See the [MyST style guide](https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide-myst/) for detailed information and conventions. + +Also see the [MyST documentation](https://myst-parser.readthedocs.io/en/latest/index.html) for detailed information on MyST, and the [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide/en) for general style conventions. + +## H2 heading + +### H3 heading + +#### H4 heading + +##### H5 heading + +## Inline formatting + +- {guilabel}`UI element` +- `code` +- {command}`command` +- {kbd}`Key` +- *Italic* +- **Bold** + +## Code blocks + +Start a code block: + + code: + - example: true + +``` +# Demonstrate a code block +code: + - example: true +``` + +```yaml +# Demonstrate a code block +code: + - example: true +``` + +(a_section_target_myst)= +## Links + +- [Canonical website](https://canonical.com/) +- {ref}`a_section_target_myst` +- {ref}`Link text ` +- {doc}`index` +- {doc}`Link text ` + +## Navigation + +Use the following syntax:: + + ```{toctree} + :hidden: + + sub-page1 + sub-page2 + ``` + +## Lists + +1. Step 1 + - Item 1 + * Sub-item + - Item 2 + 1. Sub-step 1 + 1. Sub-step 2 +1. Step 2 + 1. Sub-step 1 + - Item + 1. Sub-step 2 + +Term 1 +: Definition + +Term 2 +: Definition + +## Tables + +## Markdown tables + +| Header 1 | Header 2 | +|------------------------------------|----------| +| Cell 1
Second paragraph | Cell 2 | +| Cell 3 | Cell 4 | + +Centred: + +| Header 1 | Header 2 | +|:----------------------------------:|:--------:| +| Cell 1
Second paragraph | Cell 2 | +| Cell 3 | Cell 4 | + +## List tables + +```{list-table} + :header-rows: 1 + +* - Header 1 + - Header 2 +* - Cell 1 + + Second paragraph + - Cell 2 +* - Cell 3 + - Cell 4 +``` + +Centred: + +```{list-table} + :header-rows: 1 + :align: center + +* - Header 1 + - Header 2 +* - Cell 1 + + Second paragraph + - Cell 2 +* - Cell 3 + - Cell 4 +``` + +## Notes + +```{note} +A note. +``` + +```{tip} +A tip. +``` + +```{important} +Important information +``` + +```{caution} +This might damage your hardware! +``` + +## Images + +![Alt text](https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png) + +```{figure} https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png + :width: 100px + :alt: Alt text + + Figure caption +``` + +## Reuse + +### Keys + +Keys can be defined at the top of a file, or in a `myst_substitutions` option in `conf.py`. + +{{reuse_key}} + +{{advanced_reuse_key}} + +### File inclusion + +```{include} index.md + :start-after: include_start + :end-before: include_end +``` + +## Tabs + +````{tabs} +```{group-tab} Tab 1 + +Content Tab 1 +``` + +```{group-tab} Tab 2 +Content Tab 2 +``` +```` + +## Glossary + +```{glossary} + +some term + Definition of the example term. +``` + +{term}`some term` + +## More useful markup + +- ```{versionadded} X.Y +- {abbr}`API (Application Programming Interface)` + +---- + +## Custom extensions + +Related links at the top of the page (surrounded by `---`): + + relatedlinks: https://github.com/canonical/lxd-sphinx-extensions, [RTFM](https://www.google.com) + discourse: 12345 + +Terms that should not be checked by the spelling checker: {spellexception}`PurposelyWrong` + +A single-line terminal view that separates input from output: + +```{terminal} + :input: command + :user: root + :host: vampyr + :dir: /home/user/directory/ + +the output +``` + +A multi-line version of the same: + +```{terminal} + :user: root + :host: vampyr + :dir: /home/user/directory/ + +:input: command 1 +output 1 +:input: command 2 +output 2 +``` + +A link to a YouTube video: + +```{youtube} https://www.youtube.com/watch?v=iMLiK1fX4I0 + :title: Demo +``` diff --git a/index-myst.md b/index-myst.md new file mode 100644 index 00000000..40fdb4b8 --- /dev/null +++ b/index-myst.md @@ -0,0 +1,74 @@ +# Starter pack + +**A single sentence that says what the product is, succinctly and memorably.** +Consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et +dolore magna aliqua. + +**A paragraph of one to three short sentences, that describe what the product +does.** Urna cursus eget nunc scelerisque viverra mauris in. Nibh mauris +cursus mattis molestie a iaculis at vestibulum rhoncus est pellentesque +elit. Diam phasellus vestibulum lorem sed. + +**A third paragraph of similar length, this time explaining what need the +product meets.** Dui ut ornare lectus sit amet est. Nunc sed augue lacus +viverra vitae congue eu consequat ac libero id faucibus nisl tincidunt eget +nullam. + +**Finally, a paragraph that describes whom the product is useful for.** Nunc +non blandit massa enim nec dui nunc mattis enim. Ornare arcu odio ut sem +nulla pharetra diam porttitor leo a diam sollicitudin tempor id eu. Ipsum +dolor sit amet consectetur adipiscing elit pellentesque habitant. + +--------- + +## In this documentation + +````{grid} 1 1 2 2 + +```{grid-item-card} [Tutorials](index) + +**Start here**: a hands-on introduction to Example Product for new users +``` + +```{grid-item-card} [How-to guides](index) + +**Step-by-step guides** covering key operations and common tasks +``` + +```` + +````{grid} 1 1 2 2 +:reverse: + +```{grid-item-card} [Reference](index) + +**Technical information** - specifications, APIs, architecture +``` + +```{grid-item-card} [Explanations](index) + +**Discussion and clarification** of key topics +``` + +```` + +--------- + +## Project and community + +Example Project is a member of the Ubuntu family. It’s an open source project that warmly welcomes community projects, contributions, suggestions, fixes and constructive feedback. + +* Code of conduct +* Get support +* Join our online chat +* Contribute +* Roadmap +* Thinking about using Example Product for your next project? Get in touch! + +```{toctree} +:hidden: +:maxdepth: 2 + +self +contributing +``` diff --git a/test-md.md b/test-md.md new file mode 100644 index 00000000..da140c58 --- /dev/null +++ b/test-md.md @@ -0,0 +1,7 @@ +--- +orphan: true +discourse: 42771 +relatedlinks: https://github.com/canonical/sphinx-docs-starter-pack +--- + +# Markdown test