From d88b6f09d77d183d5019fcb46c582d15c31f4cd3 Mon Sep 17 00:00:00 2001 From: Stanislav Pankevich Date: Sun, 10 Nov 2024 18:05:50 +0100 Subject: [PATCH] docs: enable MID for all remaining documents --- docs/strictdoc_02_faq.sdoc | 40 ++++++++++++++++++++ docs/strictdoc_03_release_notes.sdoc | 50 +++++++++++++++++++++++++ docs/strictdoc_04_troubleshooting.sdoc | 20 ++++++++++ docs/strictdoc_10_contributing.sdoc | 27 +++++++++++++ docs/strictdoc_11_developer_guide.sdoc | 43 +++++++++++++++++++++ docs/strictdoc_24_development_plan.sdoc | 29 ++++++++++++++ docs/strictdoc_25_design.sdoc | 35 +++++++++++++++++ docs/strictdoc_30_credits.sdoc | 26 +++++++++++++ 8 files changed, 270 insertions(+) diff --git a/docs/strictdoc_02_faq.sdoc b/docs/strictdoc_02_faq.sdoc index d0b43df4a..dfcb39f2d 100644 --- a/docs/strictdoc_02_faq.sdoc +++ b/docs/strictdoc_02_faq.sdoc @@ -1,11 +1,28 @@ [DOCUMENT] +MID: a434bc71a7324efaaed7f5a58e56e544 TITLE: F.A.Q. UID: SDOC_FAQ OPTIONS: + ENABLE_MID: True REQUIREMENT_STYLE: Inline REQUIREMENT_IN_TOC: True +[GRAMMAR] +ELEMENTS: +- TAG: TEXT + FIELDS: + - TITLE: MID + TYPE: String + REQUIRED: False + - TITLE: STATEMENT + TYPE: String + REQUIRED: True + RELATIONS: + - TYPE: Parent + - TYPE: File + [TEXT] +MID: 5acdfccd5771492f95b70328bd599cf7 STATEMENT: >>> This document is a list of questions that people ask about StrictDoc. @@ -13,9 +30,11 @@ Missing a question or an answer? Ask it here: [LINK: SDOC_UG_CONTACT]. <<< [SECTION] +MID: e972c79015524961863e095280a81aab TITLE: What is StrictDoc? [TEXT] +MID: d8d92e4eb8254cbda8dcb37709a9df45 STATEMENT: >>> StrictDoc is software for writing technical requirements specifications. @@ -27,9 +46,11 @@ The project exists since mid-2019. [/SECTION] [SECTION] +MID: 86827c92ec3a493d8a2382b75b5277a8 TITLE: Resources about StrictDoc [TEXT] +MID: 2ba0c8fa79604b708927ffed2ef94664 STATEMENT: >>> Talks: @@ -51,9 +72,11 @@ Screencasts/tutorials: [/SECTION] [SECTION] +MID: 74235945ec4a4116aecbc883ffba54b7 TITLE: Which web server is recommended for StrictDoc documentation? [TEXT] +MID: 966a5c3babf84fc7a1454b2799d13470 STATEMENT: >>> This question can be answered in two ways. First of all, StrictDoc has its own web server that can be run with ``strictdoc server ...``. Refer to the User Guide for further information. @@ -69,9 +92,11 @@ If the project is private, you could use any server that reads HTML files from a [/SECTION] [SECTION] +MID: 2e911dedb13348bf827f078bbbca44f4 TITLE: Is StrictDoc compatible with Sphinx? [TEXT] +MID: ac35a712b4a84f4ab2b61feb15c1550d STATEMENT: >>> StrictDoc is only partially compatible with Sphinx. @@ -90,9 +115,11 @@ There is a GitHub issue `Unexpected restriction on specific RST directives / com [/SECTION] [SECTION] +MID: 235122d2c10748918c7c6ff736e39d18 TITLE: How did the SDoc text language become what it is? [TEXT] +MID: b3561dd4f8e64f11a251c3471022aece STATEMENT: >>> Shortly: The SDoc markup is a hybrid of TOML and YAML with some influence from HTML/XML and `ASN.1 `_. Using each of these formats as-is, and also the JSON format, was considered but discarded during the design. The SDoc markup has been pretty stable since its inception but the flexibility of the TextX parser allows easy modifications of the language in case of future evolutions. Any feedback to the current design of the markup language is appreciated. @@ -179,12 +206,15 @@ Taking TOML or YAML as-is didn't seem like a good option because these formats a [/SECTION] [SECTION] +MID: 1d4220cc9a5444a5bdbaee91c8c50670 TITLE: How StrictDoc compares to other tools? [SECTION] +MID: a4533ae81bfe446295242add9156198e TITLE: Doorstop [TEXT] +MID: d0c305180d8747a1b70254eaf2c4f201 STATEMENT: >>> The StrictDoc project is a close successor of another project called `Doorstop `_. @@ -238,9 +268,11 @@ to/from Doorstop format. [/SECTION] [SECTION] +MID: 5012af516d18447caa3a2dbce97d3e4a TITLE: Sphinx [TEXT] +MID: 74b6be0dc2bb485987d8731348cdf5ce STATEMENT: >>> Both Sphinx and StrictDoc are both documentation generators but StrictDoc is at a higher level of abstraction: StrictDoc's specialization is requirements and @@ -263,9 +295,11 @@ website by readthedocs which uses Sphinx under the hood. The [/SECTION] [SECTION] +MID: 515bcae39d1f48eda0b72562871ab15a TITLE: Sphinx-Needs [TEXT] +MID: 602327a9b8654e1eab4bc265e172a63d STATEMENT: >>> `Sphinx-Needs `_ is a text-based requirements management system based on Sphinx. It is implemented @@ -324,9 +358,11 @@ The difference between Sphinx-Needs and StrictDoc: [/SECTION] [SECTION] +MID: 4a77366154d74cf7ab34044bed1cd542 TITLE: FRET [TEXT] +MID: e3eb1be604c6499292339ecbe7620c60 STATEMENT: >>> `FRET `_ is a framework for the elicitation, specification, formalization and understanding of requirements. @@ -349,9 +385,11 @@ FRET's user interface is built with Electron. [/SECTION] [SECTION] +MID: ff143a18e98144bd86e10e29616c187b TITLE: How long has the StrictDoc project been around? [TEXT] +MID: 47d60404cf574aebb8c83795589c4137 STATEMENT: >>> The first StrictDoc commit dates back to ``2019-08-10``. A short development chronology of StrictDoc is as follows: @@ -388,9 +426,11 @@ See also: [LINK: SECTION-DP-Project-milestones]. [/SECTION] [SECTION] +MID: 6e5ed6bb36634220a0c583d21c96295f TITLE: Which StrictDoc statistics are available? [TEXT] +MID: 730bfedff6b24c34a6d6331051fd76d3 STATEMENT: >>> Most relevant GitHub statistics: diff --git a/docs/strictdoc_03_release_notes.sdoc b/docs/strictdoc_03_release_notes.sdoc index b074d8668..b0adfe81b 100644 --- a/docs/strictdoc_03_release_notes.sdoc +++ b/docs/strictdoc_03_release_notes.sdoc @@ -1,15 +1,35 @@ [DOCUMENT] +MID: 4277890572a94f49bda9f32a80e43c06 TITLE: Release Notes +OPTIONS: + ENABLE_MID: True + +[GRAMMAR] +ELEMENTS: +- TAG: TEXT + FIELDS: + - TITLE: MID + TYPE: String + REQUIRED: False + - TITLE: STATEMENT + TYPE: String + REQUIRED: True + RELATIONS: + - TYPE: Parent + - TYPE: File [TEXT] +MID: 0dd2649ec4784c9480eac6f4aef3158b STATEMENT: >>> This document maintains a record of all changes to StrictDoc since November 2023. It serves as a user-friendly version of the changelog, complementing the automatically generated, commit-by-commit changelog available here: `StrictDoc Changelog `_. <<< [SECTION] +MID: f76d863243b5410788e457b9c3bf1d2b TITLE: 0.2.0 (2024-11-04) [TEXT] +MID: 611e8df13d464fd1b22e5026cf3ce531 STATEMENT: >>> This release introduces several enhancements to the source code processing introduced in release 0.1.0. @@ -27,9 +47,11 @@ Additionally, caching has been centralized, and the cache directory is now confi [/SECTION] [SECTION] +MID: 83878b68483f4da2930bfb3712c08aa3 TITLE: 0.1.0 (2024-11-01) [TEXT] +MID: e37e230c932448798bd9978d4f27f32c STATEMENT: >>> This backward-compatible release introduces several new features for tracing requirements to source files: @@ -43,9 +65,11 @@ With this release, we are also transitioning to a more `semantic versioning >> This is a bugfix release with several fixes: @@ -59,9 +83,11 @@ This is a bugfix release with several fixes: [/SECTION] [SECTION] +MID: 4538fe1994bc4730b7febe3dc624f704 TITLE: 0.0.59 (2024-10-13) [TEXT] +MID: e9d5e3f8f6b04647afb95bae6b2f503a STATEMENT: >>> This release includes several important improvements. Thanks to @haxtibal for implementing and testing many of the implemented changes. @@ -85,9 +111,11 @@ This release includes several important improvements. Thanks to @haxtibal for im [/SECTION] [SECTION] +MID: 306a619f550f4be18db6dbb987df3248 TITLE: 0.0.58 (2024-06-25) [TEXT] +MID: fd7f4d5b58e54f64aa43349684a675c4 STATEMENT: >>> This is a release with a single fix and a minor documentation update. @@ -105,9 +133,11 @@ See the updated User Guide for more details. [/SECTION] [SECTION] +MID: 0795627e25e343f3b1b476b673a543ab TITLE: 0.0.57 (2024-06-23) [TEXT] +MID: f99185cb69cf47d4bc6e1bd404b67467 STATEMENT: >>> This release contains a significant, non-breaking change that affects the entire StrictDoc codebase and the SDoc data model: the ``FREETEXT-TEXT`` migration. @@ -127,9 +157,11 @@ Other changes in this release: [/SECTION] [SECTION] +MID: cd994052a0354410a550858a1f25d426 TITLE: 0.0.56 (2024-06-02) [TEXT] +MID: 61f17be85ac442a0b70003825d671ced STATEMENT: >>> This is an intermediate bugfix release before the release which will contain major changes. @@ -151,9 +183,11 @@ The following issues have been fixed: [/SECTION] [SECTION] +MID: 938f1a0fdcc94c5aaa87ddb18b880afe TITLE: 0.0.55 (2024-04-28) [TEXT] +MID: 00abb07e55534a75a8cfd50d8cfc5732 STATEMENT: >>> The ReqIF export/import feature was extended to support three new command-line options for an improved export/import interfacing with Polarion. See [LINK: SECTION-UG-ReqIF-options] for more details. @@ -165,9 +199,11 @@ StrictDoc's caching feature was extended to work around pickling errors when an [/SECTION] [SECTION] +MID: 055ee004b28647629eead8165f198579 TITLE: 0.0.54 (2024-04-17) [TEXT] +MID: e5bf489ac0684ea4b626574b5439c7dd STATEMENT: >>> 1) Two improvements were made to the Composable Documents feature, when included document's root node is edited in including document: @@ -182,9 +218,11 @@ STATEMENT: >>> [/SECTION] [SECTION] +MID: 87b7b54fa4024959bdcb42ded18f77f2 TITLE: 0.0.53 (2024-04-01) [TEXT] +MID: 2ac296f6326b4481beb7d67b95dbb23c STATEMENT: >>> The JSON export algorithm was extended to support composable documents. By default, the included documents are exported only as part of their including documents. To export both the including documents and included documents' standalone SDoc content, the option ``--included-documents`` option has to be specified with the ``export`` command. @@ -194,9 +232,11 @@ All code related to pybtex/BibTeX bibliographies has been removed from the Stric [/SECTION] [SECTION] +MID: 36a70af62b3e4a5d8bf08d9345fda095 TITLE: 0.0.52 (2024-03-25) [TEXT] +MID: 72d6e38e89cc471b8d3f46ae5654e0e6 STATEMENT: >>> The **Grammar from File** feature has been implemented. Now it is possible to declare a usual StrictDoc ``[GRAMMAR]`` in a dedicated file with an ``.sgra`` extension. When a grammar is declared in a separate file, it is possible to share this grammar between several documents. Editing of the grammars defined in ``.sgra`` files can be only done with a text editor, it is not implemented yet in the editable web interface. <<< @@ -204,9 +244,11 @@ The **Grammar from File** feature has been implemented. Now it is possible to de [/SECTION] [SECTION] +MID: 6c72f8654ea1401ea2a6e4ab82cf76e4 TITLE: 0.0.51 (2024-03-20) [TEXT] +MID: e81c4206bcb148979762ee3f2aa5c9ba STATEMENT: >>> This is a bugfix release with only one change. @@ -216,9 +258,11 @@ A regression was introduced during recent internal refactoring, resulting in mal [/SECTION] [SECTION] +MID: 413952c14412434fb237c3e909101707 TITLE: 0.0.50 (2024-03-19) [TEXT] +MID: a9d7c449d1a7400496504926c744e500 STATEMENT: >>> **Breaking change:** The "Fragments" feature has been replaced by the "Composable documents" feature: @@ -238,9 +282,11 @@ STATEMENT: >>> [/SECTION] [SECTION] +MID: 3a03dd169ffb4fe0b64f48b365a77d2e TITLE: 0.0.49 (2024-03-11) [TEXT] +MID: 0b8c8f40923744b089845afeb44223e9 STATEMENT: >>> The web interface code has been extended to allow editing arbitrary nodes. Previously, only editing the REQUIREMENT type was possible. From now on, it is possible to use the web interface to create custom grammar elements and nodes of corresponding grammar element types. @@ -258,9 +304,11 @@ The Excel export algorithm was extended to support generating multiple Excel fil [/SECTION] [SECTION] +MID: a7ed1eaf155d4f588b27ba31ecc88d4d TITLE: 0.0.48 (2024-01-24) [TEXT] +MID: 6cff333594d6430886053b59b265e806 STATEMENT: >>> The requirement-to-source traceability feature was extended to support linking requirements to the RST files. @@ -280,9 +328,11 @@ The Requirements Coverage has been transformed into **the Traceability Matrix** [/SECTION] [SECTION] +MID: 7a3620eecd1b4bd1a8eba7a373f14723 TITLE: 0.0.47 (2023-11-20) [TEXT] +MID: c422af340d5b45c48bfe89130e1bba52 STATEMENT: >>> A **query search engine** is introduced which allows filtering a documentation tree by queries like ``(node.is_requirement and "System" in node["TITLE"])``. Building on the search engine capability, the "Search" screen is introduced in the web interface. Additionally, it is now possible to specify ``--filter-requirements `` and ``filter-sections `` when running ``export`` and ``passthrough`` commands. The visual design of the project statistics was improved as well as the new design for the search screen has already landed. diff --git a/docs/strictdoc_04_troubleshooting.sdoc b/docs/strictdoc_04_troubleshooting.sdoc index 2d7ae1b5f..0b08c675c 100644 --- a/docs/strictdoc_04_troubleshooting.sdoc +++ b/docs/strictdoc_04_troubleshooting.sdoc @@ -1,16 +1,36 @@ [DOCUMENT] +MID: 5680165c90f44903b3b1dc1013b8cb59 TITLE: Troubleshooting UID: SDOC_TROUBLESHOOTING +OPTIONS: + ENABLE_MID: True + +[GRAMMAR] +ELEMENTS: +- TAG: TEXT + FIELDS: + - TITLE: MID + TYPE: String + REQUIRED: False + - TITLE: STATEMENT + TYPE: String + REQUIRED: True + RELATIONS: + - TYPE: Parent + - TYPE: File [TEXT] +MID: 7e3481d51ad14767b5c97132cad2e0a6 STATEMENT: >>> This document summarizes solutions to the most common issues reported by StrictDoc users. <<< [SECTION] +MID: 17152ac7de9f4c138b85e2956091206f TITLE: Caching issues [TEXT] +MID: 9a32ac13510d401cbc1a608259652c78 STATEMENT: >>> .. note:: diff --git a/docs/strictdoc_10_contributing.sdoc b/docs/strictdoc_10_contributing.sdoc index b319d5301..92516032d 100644 --- a/docs/strictdoc_10_contributing.sdoc +++ b/docs/strictdoc_10_contributing.sdoc @@ -1,7 +1,25 @@ [DOCUMENT] +MID: 1739e662499648d38c210a8aafbb3361 TITLE: Contributing to StrictDoc +OPTIONS: + ENABLE_MID: True + +[GRAMMAR] +ELEMENTS: +- TAG: TEXT + FIELDS: + - TITLE: MID + TYPE: String + REQUIRED: False + - TITLE: STATEMENT + TYPE: String + REQUIRED: True + RELATIONS: + - TYPE: Parent + - TYPE: File [TEXT] +MID: 13fe652f160d4af69e869c28a155437d STATEMENT: >>> Contributions to StrictDoc are welcome and appreciated. Presented below is a condensed checklist that summarises the information @@ -9,9 +27,11 @@ of the development guide, see [LINK: DEVGUIDE_GETTING_STARTED]. <<< [SECTION] +MID: ec078ab0d7564738acd2961f72abb2c9 TITLE: Contributor checklist [TEXT] +MID: ae0fc6d87b114137ab6da7c9b5647b62 STATEMENT: >>> Before opening your Pull Request, the contributor is encouraged to do the following steps: @@ -33,12 +53,15 @@ following steps: [/SECTION] [SECTION] +MID: 8b40cc35f3524bc7b4e444321c080837 TITLE: How can I help? [SECTION] +MID: 8e346888911649f2a3aaf49763aaef24 TITLE: Spread the word [TEXT] +MID: 07462b02027a423a85ab68525b78ac67 STATEMENT: >>> If you like the StrictDoc project and use it in your daily work, there are several things you could do besides contributing Pull Requests: @@ -50,9 +73,11 @@ If you like the StrictDoc project and use it in your daily work, there are sever [/SECTION] [SECTION] +MID: 2696c7fda6d440f3a290f202bee08fe6 TITLE: ReqIF users [TEXT] +MID: 9cfbb025525f41c5a195be0e637dffee STATEMENT: >>> The existing capability of StrictDoc to export/import SDoc to ReqIF is very basic. If you have to deal with ReqIF and you experience errors/crashes when using StrictDoc against ReqIF files, feel free to contribute the anonymized ReqIF files via StrictDoc Issues on GitHub, and we will take care of your specific case. @@ -62,9 +87,11 @@ It is straightforward to create an anonymized version of a ReqIF file. Just redu [/SECTION] [SECTION] +MID: 4e1edb97346c43af952c4e74f9defbe8 TITLE: TeX / LaTeX / Sphinx experts [TEXT] +MID: 75ed9362d86748269f62f5920514b7c2 STATEMENT: >>> The existing template for generating PDF documents using Sphinx looks like this: https://strictdoc.readthedocs.io/_/downloads/en/latest/pdf/. The template is maintained in a separate repository: https://github.com/strictdoc-project/sphinx-latex-reqspec-template and does a good job but could be improved in terms of look and structure used. diff --git a/docs/strictdoc_11_developer_guide.sdoc b/docs/strictdoc_11_developer_guide.sdoc index a65e02b34..79e293b49 100644 --- a/docs/strictdoc_11_developer_guide.sdoc +++ b/docs/strictdoc_11_developer_guide.sdoc @@ -1,7 +1,25 @@ [DOCUMENT] +MID: 4f05169346ab4001b6ff19e8349e8fa7 TITLE: Developer Guide +OPTIONS: + ENABLE_MID: True + +[GRAMMAR] +ELEMENTS: +- TAG: TEXT + FIELDS: + - TITLE: MID + TYPE: String + REQUIRED: False + - TITLE: STATEMENT + TYPE: String + REQUIRED: True + RELATIONS: + - TYPE: Parent + - TYPE: File [TEXT] +MID: f174b0cdec6b482daa2878c8cc0d02c3 STATEMENT: >>> This section contains everything that a StrictDoc developer/contributor should know to get the job done. @@ -17,13 +35,16 @@ Any feedback on this development guide is appreciated. <<< [SECTION] +MID: c069e4c7b4d04dd09eb73f940e947bfd UID: DEVGUIDE_GETTING_STARTED TITLE: Getting started [SECTION] +MID: 7477d397d0ca493f8e47532455d44965 TITLE: System dependencies [TEXT] +MID: df2e1de12c6b456898c48a36650813d4 STATEMENT: >>> StrictDoc itself mostly depends on other Python Pip packages, so there is nothing special to be installed. @@ -43,9 +64,11 @@ From the core Python packages, StrictDoc needs Invoke, Tox and TOML: <<< [SECTION] +MID: b7a21564c30043acbf1733d9b47bd0bc TITLE: Windows-specific: Long Path support [TEXT] +MID: 8591cf6dece04244824c3ac2a8666ba3 STATEMENT: >>> As `reported `_ by a user, Windows Long Path support has to be enabled on a Windows system. @@ -57,9 +80,11 @@ You can find information on how to enable the long paths support at https://pip. [/SECTION] [SECTION] +MID: 89ec30b9f67c489da635be391b0b0e15 TITLE: Installing StrictDoc from GitHub (developer mode) [TEXT] +MID: 2407bb186b274a58b97b54b99ba6e86f STATEMENT: >>> **Note:** Use this way of installing StrictDoc only if you want to make changes in StrictDoc's source code. Otherwise, install StrictDoc as a normal Pip package by running ``pip install strictdoc``. @@ -78,9 +103,11 @@ The ``pip_install_strictdoc_deps.py`` installs all dependencies of StrictDoc, bu [/SECTION] [SECTION] +MID: 90d5d79146e64660a71cd74ac23f6811 TITLE: Invoke for development tasks [TEXT] +MID: 452b3c24463446a497ed6b8fcdb31fef STATEMENT: >>> All development tasks are managed using `Invoke `_ in the ``tasks.py`` file. On macOS and @@ -98,9 +125,11 @@ Make sure to familiarize yourself with the available developer tasks by running: [/SECTION] [SECTION] +MID: e7ce6a2f13614974b43aba56f6ae7253 TITLE: Main "Check" task [TEXT] +MID: 09258e99cabb4455904b0e2c6687d492 STATEMENT: >>> Before doing anything else, run the main ``check`` command to make sure that StrictDoc passes all tests on your system: @@ -114,10 +143,12 @@ The ``check`` command runs all StrictDoc lint and test tasks with the only excep [/SECTION] [SECTION] +MID: 07d9a3c17be8475089844f5eb2cd8299 UID: DEVGUIDE_PYTHON_CODE TITLE: Python code [TEXT] +MID: 3012a69ef5d244d49fcb90c088d4523b STATEMENT: >>> - The version of Python is set to be as low as possible given some constraints of StrictDoc's dependencies. Ideally, the lowest Python version should only be @@ -154,10 +185,12 @@ STATEMENT: >>> [/SECTION] [SECTION] +MID: 6e9707c99199464583f091056d1ae458 UID: DEVGUIDE_GIT_WORKFLOW TITLE: Git workflow [TEXT] +MID: 0e916453596b460b84a89f722354a825 STATEMENT: >>> - The preferred Git workflow is "1 commit per 1 PR". If the work truly deserves a sequence of commits, each commit shall be self-contained and pass all checks @@ -201,9 +234,11 @@ where the context can be a major feature being added or a folder. A form of ``c [/SECTION] [SECTION] +MID: 2420b2d7a4624bd99b0f8088dfa9abff TITLE: Frontend development [TEXT] +MID: d818aad87db54985b8933f98528808ab STATEMENT: >>> The shortest path to run the server when the StrictDoc's source code is cloned: @@ -215,9 +250,11 @@ The shortest path to run the server when the StrictDoc's source code is cloned: [/SECTION] [SECTION] +MID: 73c717608cce4abca2c768f1dbfb705d TITLE: Running End-to-End Web tests [TEXT] +MID: da3cbcd69b0545988daeb0f42098830d STATEMENT: >>> .. code:: bash @@ -227,9 +264,11 @@ STATEMENT: >>> [/SECTION] [SECTION] +MID: 240dc1426d994397ac1401834b4f0ef0 TITLE: Running integration tests [TEXT] +MID: 4e307b3b950840bbbe455c1ae3238a6e STATEMENT: >>> The integration tests are run using Invoke: @@ -249,9 +288,11 @@ See `How to test command-line programs with Python tools: LIT and FileCheck >> - Every change in the functionality or the infrastructure should be documented. - Every line of documentation shall be no longer than 80 characters. StrictDoc's @@ -266,9 +307,11 @@ STATEMENT: >>> [/SECTION] [SECTION] +MID: a44e3b99323b4ac291f4b4d3948c3cc0 TITLE: Conventions [TEXT] +MID: 49b7349a3bee478cbe81d8ef25f6245c STATEMENT: >>> - ``snake_case`` everywhere, no ``kebab-case``. diff --git a/docs/strictdoc_24_development_plan.sdoc b/docs/strictdoc_24_development_plan.sdoc index 9170927ae..5ca477822 100644 --- a/docs/strictdoc_24_development_plan.sdoc +++ b/docs/strictdoc_24_development_plan.sdoc @@ -1,19 +1,38 @@ [DOCUMENT] +MID: e776a9eb7ba0455eb589787028aa0529 TITLE: Development Plan OPTIONS: + ENABLE_MID: True REQUIREMENT_STYLE: Table REQUIREMENT_IN_TOC: True +[GRAMMAR] +ELEMENTS: +- TAG: TEXT + FIELDS: + - TITLE: MID + TYPE: String + REQUIRED: False + - TITLE: STATEMENT + TYPE: String + REQUIRED: True + RELATIONS: + - TYPE: Parent + - TYPE: File + [TEXT] +MID: 2ba509874f1744cf899643b58a6a2095 STATEMENT: >>> This document presents the goals of the StrictDoc project and describes how the project is developed. <<< [SECTION] +MID: 24b0bc5efe074a419b441900d30b2876 TITLE: Project goals [TEXT] +MID: bdbd5aecefdc41bca1c88b9bce71d512 STATEMENT: >>> StrictDoc is an open-source tool for writing technical documentation and requirements management. The long-term goal of the project is to provide a capable, open-source platform for creating and managing technical documentation. @@ -41,10 +60,12 @@ StrictDoc shall be compatible with other software and engineering tools. This in [/SECTION] [SECTION] +MID: f1e3c17829fd4eebbd390fceaeb95619 UID: SECTION-DP-Project-milestones TITLE: Project milestones [TEXT] +MID: fd9294fdd2b546de993f649767371394 STATEMENT: >>> As an open-source project, StrictDoc is developed without strict deadlines, however there are certain high-level priorities that influence the development. The work is loosely organized in quarters. @@ -102,9 +123,11 @@ As an open-source project, StrictDoc is developed without strict deadlines, howe <<< [SECTION] +MID: bf9f3f05501140da8d35cde39493c72f TITLE: The roadmap diagram [TEXT] +MID: 53e101acb20e44e89de27f0f77c5f0cb STATEMENT: >>> The following diagram contains the work items at the epic and single task levels. This PNG file is exported from a draw.io diagram, where the master version of the roadmap is maintained. @@ -119,9 +142,11 @@ The following diagram contains the work items at the epic and single task levels [/SECTION] [SECTION] +MID: 625560c790a3492eaf45466b787602d7 TITLE: Versioning [TEXT] +MID: ae2a2af6e3f24f65845c6c37ea7da2e2 STATEMENT: >>> As of release 0.1.0 (2024-11-01), StrictDoc follows a `semantic versioning `_-oriented release scheme. The MAJOR.MINOR.PATCH components are managed according to the guidelines of the semantic versioning specification. <<< @@ -129,9 +154,11 @@ As of release 0.1.0 (2024-11-01), StrictDoc follows a `semantic versioning >> StrictDoc has three groups of tests: unit, integration, end-to-end tests. @@ -145,9 +172,11 @@ The end-to-end web interface tests are based on SeleniumBase test framework. [/SECTION] [SECTION] +MID: 2ae3a8822a424a9e8ad6976c2476d109 TITLE: Python baseline [TEXT] +MID: 081ee6266bab4a3a80f290c95e055a25 STATEMENT: >>> The supported version of Python is kept to be as low as possible. As of 2024-Q4, the currently supported version is Python 3.8. diff --git a/docs/strictdoc_25_design.sdoc b/docs/strictdoc_25_design.sdoc index 5fbd046eb..4c57a8e26 100644 --- a/docs/strictdoc_25_design.sdoc +++ b/docs/strictdoc_25_design.sdoc @@ -1,19 +1,38 @@ [DOCUMENT] +MID: 8e68536f7d4047ada15d3a3043580c4a TITLE: Design Document UID: SDOC_DD OPTIONS: + ENABLE_MID: True REQUIREMENT_STYLE: Table REQUIREMENT_IN_TOC: True +[GRAMMAR] +ELEMENTS: +- TAG: TEXT + FIELDS: + - TITLE: MID + TYPE: String + REQUIRED: False + - TITLE: STATEMENT + TYPE: String + REQUIRED: True + RELATIONS: + - TYPE: Parent + - TYPE: File + [TEXT] +MID: 2c006e9044074d239db4a45328633657 STATEMENT: >>> This document describes the architecture and the implementation details of StrictDoc. Compared to the User Guide that describes how to use StrictDoc, this Design Document focuses on the "how it works" of StrictDoc. <<< [SECTION] +MID: a74f4e7328714765b5e051768ca8383d TITLE: Overview [TEXT] +MID: 23937f96ac8e437d81686071cc42d6bf STATEMENT: >>> StrictDoc consists of two applications: @@ -26,9 +45,11 @@ Both applications share a significant subset of the backend and frontend logic. [/SECTION] [SECTION] +MID: f296843b2027457f851a159abafc97e3 TITLE: Building blocks [TEXT] +MID: bae7db5591fe418a857af4fb02ad4fec STATEMENT: >>> StrictDoc is based on the following open-source libraries and tools: @@ -64,10 +85,12 @@ StrictDoc is based on the following open-source libraries and tools: [/SECTION] [SECTION] +MID: 5328a6f4c8544f5e92a91279b5b2c0df UID: SECTION-DD-High-level-architecture TITLE: High-level architecture [TEXT] +MID: dcb6369b8d0949f0b06c9ee5b2188b12 STATEMENT: >>> The following diagram captures the high-level architecture of StrictDoc. @@ -80,9 +103,11 @@ The following diagram captures the high-level architecture of StrictDoc. [/SECTION] [SECTION] +MID: 9b81ed50014c412bb617e90552e58879 TITLE: StrictDoc command-line application [TEXT] +MID: 0e0fca629004496084dbe5e217874c36 STATEMENT: >>> StrictDoc command-line application is at the core of StrictDoc. The command-line interface contains commands for exporting/importing SDoc content from/to other formats and presenting documentation content to a user. @@ -97,9 +122,11 @@ The command-line application can be seen as a Model-View-Controller application: [/SECTION] [SECTION] +MID: dbcfa8a98e4f4928b0b35938d57dd644 TITLE: StrictDoc web application [TEXT] +MID: f84c0efa27954e44a8b5c1dd3517f90f STATEMENT: >>> StrictDoc Web application is based on FastAPI / Uvicorn. The end-to-end usage cycle of the web application is as follows: @@ -110,9 +137,11 @@ StrictDoc Web application is based on FastAPI / Uvicorn. The end-to-end usage cy <<< [SECTION] +MID: dd2bd75fdffe49a1a0299b804538329c TITLE: The HTML Over the Wire (Hotwire) architecture [TEXT] +MID: 5577da2187294eb986ec84d9fe26bbdf STATEMENT: >>> StrictDoc uses the `Hotwire architecture `_. @@ -128,9 +157,11 @@ Currently, the web server renders the HTML documents using the same generators t [/SECTION] [SECTION] +MID: 108af17c077c48bea04557c9d325e924 TITLE: Parsing SDoc files [TEXT] +MID: 8a926f0a67424a1eb5db73bb5abca0cd STATEMENT: >>> StrictDoc uses `textX `_ which is a ``meta-language for building Domain-Specific Languages (DSLs) in Python``. The textX itself is based on `Arpeggio `_ which is a ``Parser interpreter based on PEG grammars written in Python``. @@ -146,10 +177,12 @@ One important implementation detail of Arpeggio that influences StrictDoc user e [/SECTION] [SECTION] +MID: 4db723c7ae2c4350b2f184783cb638e7 UID: SECTION-DD-Caching-artifacts TITLE: Caching artifacts [TEXT] +MID: d351d1bf6c2a48d88e9b9bdc50e029ff STATEMENT: >>> StrictDoc caches artifacts to disk to speed up performance by avoiding repeated reading and computation of already-parsed objects. @@ -169,9 +202,11 @@ An MD5 checksum is generated for a piece of content, and a file with this checks [/SECTION] [SECTION] +MID: 4b904b71438c47fcac8aba14df2dd7c0 TITLE: HTML escaping [TEXT] +MID: e8a03713c7f644698d9a72cc79b2a299 STATEMENT: >>> StrictDoc uses Jinja2 autoescaping_ for HTML output. `Template.render`_ calls will escape any Python object unless it's explicitly marked as safe. diff --git a/docs/strictdoc_30_credits.sdoc b/docs/strictdoc_30_credits.sdoc index 42ea646a2..eeb518d98 100644 --- a/docs/strictdoc_30_credits.sdoc +++ b/docs/strictdoc_30_credits.sdoc @@ -1,7 +1,25 @@ [DOCUMENT] +MID: d92baa6b8cf745a2ab6be86616b06277 TITLE: Credits +OPTIONS: + ENABLE_MID: True + +[GRAMMAR] +ELEMENTS: +- TAG: TEXT + FIELDS: + - TITLE: MID + TYPE: String + REQUIRED: False + - TITLE: STATEMENT + TYPE: String + REQUIRED: True + RELATIONS: + - TYPE: Parent + - TYPE: File [TEXT] +MID: 18cf0af34c194590b3eb391c2ef94074 STATEMENT: >>> As an open-source project, StrictDoc is based on the work of many people and organizations: @@ -14,9 +32,11 @@ This page gives due credit to everyone who made StrictDoc possible. <<< [SECTION] +MID: c89b5ba9c6dc427497647b64048a2c98 TITLE: Contributions to StrictDoc [TEXT] +MID: e6de83e242bc4aea96622a2e7585f135 STATEMENT: >>> The core team: @stanislaw and @mettta. @@ -40,9 +60,11 @@ Single/smaller contributions can be also seen on the `StrictDoc's Insights/Contr [/SECTION] [SECTION] +MID: 4d59a5df65d547e685cb491937793f69 TITLE: Open source software [TEXT] +MID: 4428ac9ec3504dda9f1e1e845ffb3c75 STATEMENT: >>> StrictDoc is based on other open source components. Without this support, we would have never reached where we are today. @@ -72,9 +94,11 @@ Refer to the `configuration file >> StrictDoc is hosted on `GitHub `_ and uses `GitHub Actions `_ to run all of its build, test and release tasks. As an open-source project, StrictDoc gets these services from GitHub for free. @@ -84,9 +108,11 @@ StrictDoc's documentation is hosted on `Read the Docs ` [/SECTION] [SECTION] +MID: 43ccb6448b9d4b65a2c40df54d1707aa TITLE: Free and commercial IDEs by JetBrains [TEXT] +MID: b4729e592d104fe3818c8949615ffef9 STATEMENT: >>> For Python development, the StrictDoc core team uses the community version of `PyCharm `_