diff --git a/.gitignore b/.gitignore index f771ea3..2199cea 100644 --- a/.gitignore +++ b/.gitignore @@ -2,9 +2,10 @@ node_modules package-lock.json *.vsix -/_* # tests/integration .lit_test_times.txt **/Output/** +# local drafts and examples +docs/_* diff --git a/.vscodeignore b/.vscodeignore index d899015..7ac3a73 100644 --- a/.vscodeignore +++ b/.vscodeignore @@ -4,8 +4,11 @@ .gitattributes vsc-extension-quickstart.md -# Example content (not for users) -_strictdoc_examples/** +# GitHub workflows, CI +.github/** + +# Screenshots and extra assets (excluded from VSIX) +assets/** # Development & test code (Node) parse_syntax.js @@ -17,8 +20,13 @@ tasks.py requirements.txt tests/** -# GitHub workflows, CI -.github/** +# Project documentation and example content (not for users) +docs/** -# Screenshots and extra assets (excluded from VSIX) -assets/** +# ───────────────────────────────────────────── +# ❓ For committers: add uncertain files here +# If you're not sure where to categorize a dev/test file, +# list it temporarily under this section. +# ───────────────────────────────────────────── +# e.g. +# temp_script.py diff --git a/README.md b/README.md index 620a235..6ba80d7 100644 --- a/README.md +++ b/README.md @@ -189,3 +189,7 @@ Now, open the `test.sdoc` file using the `Generic Text Editor`. You should see the SDoc syntax highlighted: ![](assets/Eclipse/Screenshot_Eclipse_12.png) + +--- + +📌 See [docs/contributing.md](./docs/contributing.md) for contribution and maintenance notes. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..410391b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,11 @@ +# Documentation + +This folder contains internal project documentation for contributors and maintainers. + +## Contents + +- `publishing.md`: Instructions for building and publishing the VS Code extension +- `contributing.md`: Notes for contributors +- `examples/`: Example documents and screenshots for testing and demonstration + +> Avoid putting user-facing documentation in this folder. Use the main `README.md` for that. diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..7ad3122 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,9 @@ +# Committer Guidelines + +Hi! Thanks for contributing 🤝 +Just a couple of notes to keep things clean and consistent: + +## Dev/Test files + +✅ When adding development or test files, update `.vscodeignore` accordingly — exclude anything not required in the final `.vsix` package. +Use the dedicated section at the bottom of `.vscodeignore` if unsure where a file belongs. diff --git a/docs/examples/example_invalid.sdoc b/docs/examples/example_invalid.sdoc new file mode 100644 index 0000000..4c3176a --- /dev/null +++ b/docs/examples/example_invalid.sdoc @@ -0,0 +1,46 @@ +[DOCUMENT] +TITLE: Document with deprecated REQ_PREFIX, REQUIREMENT_STYLE, REQUIREMENT_IN_TOC +REQ_PREFIX: _DEPRECATED_ +OPTIONS: + REQUIREMENT_STYLE: Inline + REQUIREMENT_IN_TOC: True + +[GRAMMAR] +ELEMENTS: +- TAG: DEPRECATED_TYPE_REF_CHOICES + FIELDS: + - TITLE: DEPRECATED_1 + TYPE: ParentReqReference + - TITLE: DEPRECATED_2 + TYPE: FileReference + - TITLE: DEPRECATED_3 + TYPE: BibReference + +[SOME_EXAMPLE_NODE] +TITLE: Node with deprecated REFS tag +REFS: +- TYPE: File + VALUE: examples/example_source_files/file2.py + +[SECTION] +TITLE: DEPRECATED SECTION TAG + +[/SECTION] + +[COMPOSITE_REQUIREMENT] +STATEMENT: This tag name is possible, but will not create a composite node. + +[/COMPOSITE_REQUIREMENT] + +[ANY_NAME] +STATEMENT: Only the composite node has a closing tag, and it has double brackets. + +[/ANY_NAME] + +[[GRAMMAR]] + +[[/GRAMMAR]] + +[[DOCUMENT_FROM_FILE]] + +[[/DOCUMENT_FROM_FILE]] diff --git a/docs/examples/example_valid.sdoc b/docs/examples/example_valid.sdoc new file mode 100644 index 0000000..b73f6b2 --- /dev/null +++ b/docs/examples/example_valid.sdoc @@ -0,0 +1,122 @@ +[DOCUMENT] +MID: b7bcca934cd148c3855beb4c85723bc5 +TITLE: Example document title +UID: ABCD1234_QWERTY +VERSION: 0.0.0.0 +CLASSIFICATION: Public +PREFIX: FOO_SDOC-SSS- +ROOT: True +OPTIONS: + ENABLE_MID: True + MARKUP: RST + AUTO_LEVELS: On + VIEW_STYLE: Inline + NODE_IN_TOC: True +METADATA: + FOO: BAR + +[GRAMMAR] +ELEMENTS: +- TAG: NODE_NAME_ONE + PROPERTIES: + IS_COMPOSITE: True + PREFIX: None + VIEW_STYLE: Narrative + FIELDS: + - TITLE: MID + TYPE: String + REQUIRED: False + - TITLE: UID + TYPE: String + REQUIRED: False + - TITLE: LEVEL + TYPE: String + REQUIRED: True + - TITLE: PREFIX + TYPE: String + REQUIRED: True + - TITLE: STATUS + TYPE: String + REQUIRED: False + - TITLE: TAGS + TYPE: Tag + REQUIRED: False + - TITLE: TITLE + TYPE: String + REQUIRED: True + - TITLE: STATEMENT + TYPE: String + REQUIRED: False + - TITLE: RATIONALE + TYPE: String + REQUIRED: False + - TITLE: COMMENT + TYPE: String + REQUIRED: False + RELATIONS: + - TYPE: Parent + ROLE: Implements + - TYPE: Child + ROLE: Refines + - TYPE: File +- TAG: NODE_NAME_TWO + FIELDS: + - TITLE: UID + TYPE: String + REQUIRED: True + - TITLE: TITLE + TYPE: String + REQUIRED: True + - TITLE: VERIFICATION + TYPE: MultipleChoice(Review, Analysis, Inspection, Test) + REQUIRED: True + - TITLE: FIELD_ONE + TYPE: SingleChoice(A|B|C) + REQUIRED: False + - TITLE: FIELD_TWO + TYPE: MultipleChoice(A|B|C) + REQUIRED: False + +[[NODE_NAME_ONE]] +MID: 668d18a7489043b38dd435933319e8 +UID: ABC-123 +LEVEL: None +STATUS: Draft +TAGS: one, two +TITLE: Example composite node title +STATEMENT: System A shall do B. +RATIONALE: Rationale. +COMMENT: Test comment. +RELATIONS: +- TYPE: Parent + VALUE: SDOC-SSS-88 + ROLE: Refines +- TYPE: Parent + VALUE: SDOC-SSS-58 + FUNCTION: Foo.hello_world_2 + +[NODE_NAME_TWO] +UID: QWE-6789 +TITLE: Example non-composite node title +VERIFICATION: Review, Test +FIELD_ONE: A +FIELD_TWO: B, C + +[[/NODE_NAME_ONE]] + +[SOME_EXAMPLE_NODE] +STATEMENT: >>> +MathJax in requirement's STATEMENT: + +.. raw:: latex html + + $$ + \mathbf{\underline{k}}_{\text{a}} = + \mathbf{\underline{i}}_{\text{a}} \times + \mathbf{\underline{j}}_{\text{a}} + $$ +<<< + +[DOCUMENT_FROM_FILE] +FILE: ddd/ddd/ddd\f456inc-_lude.ssec +INCLUDE_TITLE: True diff --git a/docs/publishing.md b/docs/publishing.md new file mode 100644 index 0000000..74c209f --- /dev/null +++ b/docs/publishing.md @@ -0,0 +1,85 @@ +# Publishing the StrictDoc VSCode Extension + +This document explains how to package and publish the extension to the [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/). + +## 1. Checklist before publishing + +* ✅ Version in `package.json` has been bumped. +* ✅ Only necessary files are included in the `.vsix` package. +* ✅ `.vscodeignore` is up-to-date and excludes: + + * tests/\*\* + * parse\_syntax.js + * .github/\*\* + * assets/\*\* + * node\_modules/\*\* (if not needed at runtime) + * any other internal scripts or data + +## 2. Bump the version + +### 2.1. manually (recommended) + +Update `version` in `package.json` (manually): + +```json +"version": "0.2.1" +``` + +> ⚠️ This must be **higher** than the currently published version. + +### 2.2. automatically via npm version + +You can also use: + +```bash +npm version patch|minor|major +``` + +it will: + * Update the version number in package.json and package-lock.json; + * Automatically create a Git commit with a message like v0.2.2; + * Create a Git tag with the same version name (v0.2.2). + +If you want to avoid creating the commit and tag, use the --no-git-tag-version flag: + +```bash +npm version patch --no-git-tag-version +``` + +## 3. Build the extension + +Run: + +```bash +vsce package +``` + +This generates a `.vsix` file (e.g., `strictdoc-0.2.1.vsix`). + +## 4. Publish to Marketplace + +If not logged in: + +```bash +vsce login StrictDoc +``` + +To publish: + +```bash +vsce publish +``` + +## 5. Verify + +Check that the version and content appear here (may take a minute or two): + +* [https://marketplace.visualstudio.com/items?itemName=StrictDoc.strictdoc](https://marketplace.visualstudio.com/items?itemName=StrictDoc.strictdoc) + +--- + +## Notes + +* Images used in `README.md` will be loaded from GitHub if paths are relative. +* You don't need to ship them inside `.vsix`. +* Use the `docs/` folder for internal notes, not visible on Marketplace.