{"id":29013853,"url":"https://github.com/armmbed/snippet","last_synced_at":"2025-06-25T20:12:14.564Z","repository":{"id":62563338,"uuid":"123312629","full_name":"ARMmbed/snippet","owner":"ARMmbed","description":"A Python3 tool to extract code snippets from source files","archived":false,"fork":false,"pushed_at":"2024-02-21T07:02:17.000Z","size":152,"stargazers_count":7,"open_issues_count":3,"forks_count":23,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-05-24T19:09:02.039Z","etag":null,"topics":["code","documentation-generator","documentation-tool","project-management","snippet","snippet-generator"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ARMmbed.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null}},"created_at":"2018-02-28T16:37:16.000Z","updated_at":"2025-04-06T08:24:34.000Z","dependencies_parsed_at":"2022-11-03T15:45:25.093Z","dependency_job_id":null,"html_url":"https://github.com/ARMmbed/snippet","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/ARMmbed/snippet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARMmbed%2Fsnippet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARMmbed%2Fsnippet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARMmbed%2Fsnippet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARMmbed%2Fsnippet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ARMmbed","download_url":"https://codeload.github.com/ARMmbed/snippet/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARMmbed%2Fsnippet/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261945405,"owners_count":23234243,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code","documentation-generator","documentation-tool","project-management","snippet","snippet-generator"],"created_at":"2025-06-25T20:12:13.611Z","updated_at":"2025-06-25T20:12:14.541Z","avatar_url":"https://github.com/ARMmbed.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Snippet\r\n\r\n![Package](https://badgen.net/badge/Package/code-snippet/grey) \r\n[![Documentation](https://badgen.net/badge/Documentation/GitHub%20Pages/blue?icon=github)](https://armmbed.github.io/snippet) \r\n[![PyPI](https://badgen.net/pypi/v/code-snippet)](https://pypi.org/project/code-snippet/) \r\n[![PyPI - Status](https://img.shields.io/pypi/status/code-snippet)](https://pypi.org/project/code-snippet/) \r\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/code-snippet)](https://pypi.org/project/code-snippet/) \r\n \r\n[![License](https://badgen.net/pypi/license/code-snippet)](https://github.com/ARMmbed/snippet/blob/master/LICENSE) \r\n[![Compliance](https://badgen.net/badge/License%20Report/compliant/green?icon=libraries)](https://armmbed.github.io/snippet/third_party_IP_report.html) \r\n\r\n[![Build Status](https://dev.azure.com/mbed-tools/code-snippet/_apis/build/status/Build%20and%20Release?branchName=master\u0026stageName=CI%20Checkpoint)](https://dev.azure.com/mbed-tools/code-snippet/_build/latest?definitionId=15\u0026branchName=master)\r\n[![Test Coverage](https://codecov.io/gh/ARMmbed/code-snippet/branch/master/graph/badge.svg)](https://codecov.io/gh/ARMmbed/snippet)\r\n[![Maintainability](https://api.codeclimate.com/v1/badges/2050e74c1c485109d357/maintainability)](https://codeclimate.com/github/ARMmbed/snippet/maintainability)\r\n\r\n## Overview\r\n\r\nA tool to extract code snippets from source files\r\n\r\nEssentially, snippet extracts marked sections of text from a given set of input files and saves them elsewhere.\r\n\r\nFeatures include:\r\n- Works on any text file, e.g.\r\nany coding language by reading from source files\r\n- Uses customisable markup syntax\r\n- Writes to templated output (e.g. `.md` code blocks)\r\n- Hides sections from output\r\n- Performs validation to help avoid snippets breaking as code changes\r\n\r\n## Rationale \r\nCode documentation usually needs a written example demonstrating use of some code. This example code can however become quite easily outdated as a project evolves or even contain its own errors. \r\nOne solution is to write the examples as tests which can be run within the test system of choice. This ensures that the code of the examples is always valid and working. `snippet`  can then be used to extract the relevant and informative part of the test and put it in a form which can then be rendered by the documentation system, providing fully tested code examples. \r\n \r\n## Releases\r\n\r\nFor release notes and a history of changes of all **production** releases, please see the following:\r\n\r\n- [Changelog](https://github.com/ARMmbed/snippet/blob/master/CHANGELOG.md)\r\n\r\nFor a the list of all available versions please, please see the:\r\n\r\n- [PyPI Release History](https://pypi.org/project/code-snippet/#history)\r\n\r\n## Versioning\r\n\r\nThe version scheme used follows [PEP440](https://www.python.org/dev/peps/pep-0440/) and \r\n[Semantic Versioning](https://semver.org/). For production quality releases the version will look as follows:\r\n\r\n- `\u003cmajor\u003e.\u003cminor\u003e.\u003cpatch\u003e`\r\n\r\nBeta releases are used to give early access to new functionality, for testing and to get feedback on experimental \r\nfeatures. As such these releases may not be stable and should not be used for production. Additionally any interfaces\r\nintroduced in a beta release may be removed or changed without notice. For **beta** releases the version will look as\r\nfollows:\r\n\r\n- `\u003cmajor\u003e.\u003cminor\u003e.\u003cpatch\u003e-beta.\u003cpre-release-number\u003e`\r\n\r\n## Installation\r\n\r\nIt is recommended that a virtual environment such as [Pipenv](https://github.com/pypa/pipenv/blob/master/README.md) is\r\nused for all installations to avoid Python dependency conflicts.\r\n\r\nTo install the most recent production quality release use:\r\n\r\n```\r\npip install code-snippet\r\n```\r\n\r\nTo install a specific release:\r\n\r\n```\r\npip install code-snippet==\u003cversion\u003e\r\n```\r\n\r\n## Usage\r\n### Configuration \r\nPlace a config file in the [toml format](https://github.com/toml-lang/toml) \r\nin your project directory (e.g. `snippet.toml`). Any value defined in [the config object](https://github.com/ARMmbed/snippet/blob/master/src/snippet/config.py#L8) \r\ncan be overridden. \r\n \r\nAs an example, basic configuration typically includes input and output directories: \r\n \r\n``` \r\n[snippet] \r\ninput_glob = 'tests/unit/*.py' \r\noutput_dir = 'docs/examples' \r\n``` \r\n### Run \r\nRun the following command in your project: \r\n \r\n``` \r\nsnippet \r\n``` \r\n \r\nAlternatively, run snippet from anywhere and specify a working directory and config file: \r\n``` \r\nsnippet path/to/root --config=path/to/config.toml \r\n``` \r\nConfig files can be specified as glob patterns, defaulting to `*.toml`, and can \r\nbe set multiple times. Multiple files will be loaded in the order specified \r\nand discovered. Settings loaded last will take precedence. \r\n\r\nFor more information about how to use the tool, please have a look at the [Usage page](./USAGE.md) \r\nThe full CLI options are: \r\n``` \r\n\u003e snippet --help \r\nusage: __main__.py [-h] [--config CONFIG] [-v] [dir] \r\n \r\npositional arguments: \r\n  dir              path to project root, used by any relative paths in loaded \r\n                   configs [cwd] \r\n \r\noptional arguments: \r\n  -h, --help       show this help message and exit \r\n  --config CONFIG  paths (or globs) to config files \r\n  -v, --verbosity  increase output verbosity \r\n``` \r\n\r\nInterface definition and usage documentation (for developers of tooling) is available for the most recent\r\nproduction release here:\r\n\r\n- [GitHub Pages](https://armmbed.github.io/snippet)\r\n\r\n## Project Structure\r\n\r\nThe follow described the major aspects of the project structure:\r\n\r\n- `azure-pipelines/` - CI configuration files for Azure Pipelines.\r\n- `docs/` - Interface definition and usage documentation.\r\n- `examples/` - Usage examples.\r\n- `snippet/` - Python source files.\r\n- `news/` - Collection of news files for unreleased changes.\r\n- `tests/` - Unit and integration tests.\r\n\r\n## Getting Help\r\n\r\n- For interface definition and usage documentation, please see [GitHub Pages](https://armmbed.github.io/snippet).\r\n- For a list of known issues and possible work arounds, please see [Known Issues](KNOWN_ISSUES.md).\r\n- To raise a defect or enhancement please use [GitHub Issues](https://github.com/ARMmbed/snippet/issues).\r\n- To ask a question please use the [Mbed Forum](https://forums.mbed.com/).\r\n\r\n## Contributing\r\n\r\n- Snippet is an open source project and we are committed to fostering a welcoming community, please see our\r\n  [Code of Conduct](https://github.com/ARMmbed/snippet/blob/master/CODE_OF_CONDUCT.md) for more information.\r\n- For ways to contribute to the project, please see the [Contributions Guidelines](https://github.com/ARMmbed/snippet/blob/master/CONTRIBUTING.md)\r\n- For a technical introduction into developing this package, please see the [Development Guide](https://github.com/ARMmbed/snippet/blob/master/DEVELOPMENT.md)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farmmbed%2Fsnippet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farmmbed%2Fsnippet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farmmbed%2Fsnippet/lists"}