From fe85f540ee136663dffd7a56d6c9425e0e57934e Mon Sep 17 00:00:00 2001 From: Stanislav Pankevich Date: Sun, 8 May 2022 16:29:02 +0200 Subject: [PATCH 1/3] docs: fix a broken link from excel requiremenent to excel generator --- docs/strictdoc-2-requirements.sdoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/strictdoc-2-requirements.sdoc b/docs/strictdoc-2-requirements.sdoc index dea59dae5..dcfd5b083 100644 --- a/docs/strictdoc-2-requirements.sdoc +++ b/docs/strictdoc-2-requirements.sdoc @@ -337,7 +337,7 @@ STATEMENT: StrictDoc shall support exporting documents to Sphinx/RST format. UID: SDOC-GEN-EXCEL-EXPORT REFS: - TYPE: File - VALUE: strictdoc/export/excel/excel_generator.py + VALUE: strictdoc/backend/excel/export/excel_generator.py TITLE: Excel Export STATEMENT: StrictDoc shall support exporting documents to Excel format. From 0b781c602a630d87964c0921ec8da1c079074086 Mon Sep 17 00:00:00 2001 From: Stanislav Pankevich Date: Sun, 8 May 2022 16:45:05 +0200 Subject: [PATCH 2/3] docs: update documentation, introduce design document --- docs/sphinx/source/index.rst | 7 +- ...n.rst => strictdoc-2-development-plan.rst} | 31 +- ...ments.rst => strictdoc-3-requirements.rst} | 28 - docs/sphinx/source/strictdoc-4-design.rst | 31 + ...-4-backlog.rst => strictdoc-5-backlog.rst} | 0 ...sdoc => strictdoc-2-development-plan.sdoc} | 30 +- ...nts.sdoc => strictdoc-3-requirements.sdoc} | 32 - docs/strictdoc-4-design.sdoc | 36 ++ ...-backlog.sdoc => strictdoc-5-backlog.sdoc} | 4 +- .../strictdoc-html/_static/_requirement.css | 48 ++ ...ictdoc-2-development-plan-DEEP-TRACE.html} | 67 +-- ...> strictdoc-2-development-plan-TABLE.html} | 55 +- ...> strictdoc-2-development-plan-TRACE.html} | 61 +- ...html => strictdoc-2-development-plan.html} | 552 ++++++++++-------- ... strictdoc-3-requirements-DEEP-TRACE.html} | 232 +------- ...ml => strictdoc-3-requirements-TABLE.html} | 179 +----- ...ml => strictdoc-3-requirements-TRACE.html} | 223 +------ ...nts.html => strictdoc-3-requirements.html} | 321 ++++------ .../docs/strictdoc-4-design-DEEP-TRACE.html | 308 ++++++++++ .../docs/strictdoc-4-design-TABLE.html | 269 +++++++++ .../docs/strictdoc-4-design-TRACE.html | 306 ++++++++++ .../docs/strictdoc-4-design.html | 264 +++++++++ ...ml => strictdoc-5-backlog-DEEP-TRACE.html} | 26 +- ...LE.html => strictdoc-5-backlog-TABLE.html} | 18 +- ...CE.html => strictdoc-5-backlog-TRACE.html} | 26 +- ...-backlog.html => strictdoc-5-backlog.html} | 75 ++- docs/strictdoc-html/strictdoc-html/index.html | 68 ++- .../strictdoc-html/requirements_coverage.html | 487 +++++++-------- .../_shared/requirement_table.jinja.html | 4 +- .../export/01_strictdoc_smoke_test/test.itest | 29 +- .../test.itest | 41 +- .../passthrough/01_hello_world/test.itest | 15 +- 32 files changed, 2246 insertions(+), 1627 deletions(-) rename docs/sphinx/source/{strictdoc-3-development-plan.rst => strictdoc-2-development-plan.rst} (88%) rename docs/sphinx/source/{strictdoc-2-requirements.rst => strictdoc-3-requirements.rst} (94%) create mode 100644 docs/sphinx/source/strictdoc-4-design.rst rename docs/sphinx/source/{strictdoc-4-backlog.rst => strictdoc-5-backlog.rst} (100%) rename docs/{strictdoc-3-development-plan.sdoc => strictdoc-2-development-plan.sdoc} (84%) rename docs/{strictdoc-2-requirements.sdoc => strictdoc-3-requirements.sdoc} (93%) create mode 100644 docs/strictdoc-4-design.sdoc rename docs/{strictdoc-4-backlog.sdoc => strictdoc-5-backlog.sdoc} (99%) rename docs/strictdoc-html/strictdoc-html/docs/{strictdoc-3-development-plan-DEEP-TRACE.html => strictdoc-2-development-plan-DEEP-TRACE.html} (93%) rename docs/strictdoc-html/strictdoc-html/docs/{strictdoc-3-development-plan-TABLE.html => strictdoc-2-development-plan-TABLE.html} (90%) rename docs/strictdoc-html/strictdoc-html/docs/{strictdoc-3-development-plan-TRACE.html => strictdoc-2-development-plan-TRACE.html} (93%) rename docs/strictdoc-html/strictdoc-html/docs/{strictdoc-3-development-plan.html => strictdoc-2-development-plan.html} (55%) rename docs/strictdoc-html/strictdoc-html/docs/{strictdoc-2-requirements-DEEP-TRACE.html => strictdoc-3-requirements-DEEP-TRACE.html} (94%) rename docs/strictdoc-html/strictdoc-html/docs/{strictdoc-2-requirements-TABLE.html => strictdoc-3-requirements-TABLE.html} (93%) rename docs/strictdoc-html/strictdoc-html/docs/{strictdoc-2-requirements-TRACE.html => strictdoc-3-requirements-TRACE.html} (94%) rename docs/strictdoc-html/strictdoc-html/docs/{strictdoc-2-requirements.html => strictdoc-3-requirements.html} (90%) create mode 100644 docs/strictdoc-html/strictdoc-html/docs/strictdoc-4-design-DEEP-TRACE.html create mode 100644 docs/strictdoc-html/strictdoc-html/docs/strictdoc-4-design-TABLE.html create mode 100644 docs/strictdoc-html/strictdoc-html/docs/strictdoc-4-design-TRACE.html create mode 100644 docs/strictdoc-html/strictdoc-html/docs/strictdoc-4-design.html rename docs/strictdoc-html/strictdoc-html/docs/{strictdoc-4-backlog-DEEP-TRACE.html => strictdoc-5-backlog-DEEP-TRACE.html} (98%) rename docs/strictdoc-html/strictdoc-html/docs/{strictdoc-4-backlog-TABLE.html => strictdoc-5-backlog-TABLE.html} (98%) rename docs/strictdoc-html/strictdoc-html/docs/{strictdoc-4-backlog-TRACE.html => strictdoc-5-backlog-TRACE.html} (98%) rename docs/strictdoc-html/strictdoc-html/docs/{strictdoc-4-backlog.html => strictdoc-5-backlog.html} (94%) diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst index 7b2ec2962..468c3ab7c 100644 --- a/docs/sphinx/source/index.rst +++ b/docs/sphinx/source/index.rst @@ -5,6 +5,7 @@ Welcome to StrictDoc's documentation! :maxdepth: 1 strictdoc-1-user-manual - strictdoc-2-requirements - strictdoc-3-development-plan - strictdoc-4-backlog + strictdoc-2-development-plan + strictdoc-3-requirements + strictdoc-4-design + strictdoc-5-backlog diff --git a/docs/sphinx/source/strictdoc-3-development-plan.rst b/docs/sphinx/source/strictdoc-2-development-plan.rst similarity index 88% rename from docs/sphinx/source/strictdoc-3-development-plan.rst rename to docs/sphinx/source/strictdoc-2-development-plan.rst index 142a06078..2e579d675 100644 --- a/docs/sphinx/source/strictdoc-3-development-plan.rst +++ b/docs/sphinx/source/strictdoc-2-development-plan.rst @@ -28,10 +28,6 @@ requirements and specifications documents **Comment:** Technical documentation is hard, it can be an extremely laborious process. Software shall support engineers in their work with documentation. -**Comment:** The state of the art for many small companies working with -requirements: using Excel for requirements management in the projects with -hundreds or thousands of requirements. - **Children:** - ``[SDOC-HIGH-REQS-MANAGEMENT]`` :ref:`SDOC-HIGH-REQS-MANAGEMENT` @@ -108,20 +104,21 @@ to do a more advanced analysis of requirements and requirement trees: - ``[BACKLOG-FUZZY-SEARCH]`` :ref:`BACKLOG-FUZZY-SEARCH` -Two frontends -============= +User interfaces +=============== -There are two frontends for StrictDoc: +There are two user interfaces for StrictDoc: -1) Text frontend -2) Web frontend +1) Command-line interface (CLI) +2) Web interface -The text frontend is already developed, the web frontend is incubation. +The CLI interface is already developed, the web interface is (slow) +work-in-progress. .. _FRONTEND-1-TEXT: -Text frontend -------------- +Command-line interface +---------------------- .. list-table:: :align: left @@ -130,7 +127,7 @@ Text frontend * - **UID:** - FRONTEND-1-TEXT -... +StrictDoc shall provide a command-line interface. **Children:** @@ -138,8 +135,8 @@ Text frontend .. _FRONTEND-2-WEB: -Web frontend ------------- +Web interface +------------- .. list-table:: :align: left @@ -148,7 +145,7 @@ Web frontend * - **UID:** - FRONTEND-2-WEB -... +StrictDoc shall provide a web interface. **Children:** @@ -157,6 +154,6 @@ Web frontend Development team ================ -StrictDoc is a spare time project developed and maintained by a single person +StrictDoc is a spare time project developed and maintained by two people with occasional contributions from the Open Source community. diff --git a/docs/sphinx/source/strictdoc-2-requirements.rst b/docs/sphinx/source/strictdoc-3-requirements.rst similarity index 94% rename from docs/sphinx/source/strictdoc-2-requirements.rst rename to docs/sphinx/source/strictdoc-3-requirements.rst index 832b968a6..07357b9ee 100644 --- a/docs/sphinx/source/strictdoc-2-requirements.rst +++ b/docs/sphinx/source/strictdoc-3-requirements.rst @@ -527,31 +527,3 @@ StrictDoc shall generate source coverage information. **Comment:** Source coverage screen shows how source files are linked with requirements. -Design decisions -================ - -Building blocks ---------------- - -TextX -~~~~~ - -TextX shall be used for StrictDoc grammar definition and parsing of the sdoc files. - -**Comment:** TextX is an easy-to-install Python tool. It is fast, works out of the box. - -Jinja2 -~~~~~~ - -Jinja2 shall be used for rendering HTML templates. - -Sphinx and Docutils -~~~~~~~~~~~~~~~~~~~ - -Sphinx and Docutils shall be used for the following capabilities: - -- Support of Restructured Text (reST) format -- Generation of RST documents into HTML -- Generation of RST documents into PDF using LaTeX -- Generating documentation websites using Sphinx - diff --git a/docs/sphinx/source/strictdoc-4-design.rst b/docs/sphinx/source/strictdoc-4-design.rst new file mode 100644 index 000000000..023b495c1 --- /dev/null +++ b/docs/sphinx/source/strictdoc-4-design.rst @@ -0,0 +1,31 @@ +StrictDoc Design Document +$$$$$$$$$$$$$$$$$$$$$$$$$ + +Design decisions +================ + +Building blocks +--------------- + +TextX +~~~~~ + +TextX shall be used for StrictDoc grammar definition and parsing of the sdoc files. + +**Comment:** TextX is an easy-to-install Python tool. It is fast, works out of the box. + +Jinja2 +~~~~~~ + +Jinja2 shall be used for rendering HTML templates. + +Sphinx and Docutils +~~~~~~~~~~~~~~~~~~~ + +Sphinx and Docutils shall be used for the following capabilities: + +- Support of Restructured Text (reST) format +- Generation of RST documents into HTML +- Generation of RST documents into PDF using LaTeX +- Generating documentation websites using Sphinx + diff --git a/docs/sphinx/source/strictdoc-4-backlog.rst b/docs/sphinx/source/strictdoc-5-backlog.rst similarity index 100% rename from docs/sphinx/source/strictdoc-4-backlog.rst rename to docs/sphinx/source/strictdoc-5-backlog.rst diff --git a/docs/strictdoc-3-development-plan.sdoc b/docs/strictdoc-2-development-plan.sdoc similarity index 84% rename from docs/strictdoc-3-development-plan.sdoc rename to docs/strictdoc-2-development-plan.sdoc index 716337113..1ec0060d4 100644 --- a/docs/strictdoc-3-development-plan.sdoc +++ b/docs/strictdoc-2-development-plan.sdoc @@ -27,11 +27,6 @@ COMMENT: >>> Technical documentation is hard, it can be an extremely laborious process. Software shall support engineers in their work with documentation. <<< -COMMENT: >>> -The state of the art for many small companies working with -requirements: using Excel for requirements management in the projects with -hundreds or thousands of requirements. -<<< [REQUIREMENT] UID: GOAL-2-REDUCE-DOCUMENTATION-HAZARDS @@ -83,29 +78,30 @@ to do a more advanced analysis of requirements and requirement trees: [/SECTION] [SECTION] -TITLE: Two frontends +TITLE: User interfaces [FREETEXT] -There are two frontends for StrictDoc: +There are two user interfaces for StrictDoc: -1) Text frontend -2) Web frontend +1) Command-line interface (CLI) +2) Web interface -The text frontend is already developed, the web frontend is incubation. +The CLI interface is already developed, the web interface is (slow) +work-in-progress. [/FREETEXT] [REQUIREMENT] -UID: FRONTEND-1-TEXT -TITLE: Text frontend +UID: UI-1-TEXT +TITLE: Command-line interface STATEMENT: >>> -... +StrictDoc shall provide a command-line interface. <<< [REQUIREMENT] -UID: FRONTEND-2-WEB -TITLE: Web frontend +UID: UI-2-WEB +TITLE: Web interface STATEMENT: >>> -... +StrictDoc shall provide a web interface. <<< [/SECTION] @@ -114,7 +110,7 @@ STATEMENT: >>> TITLE: Development team [FREETEXT] -StrictDoc is a spare time project developed and maintained by a single person +StrictDoc is a spare time project developed and maintained by two people with occasional contributions from the Open Source community. [/FREETEXT] diff --git a/docs/strictdoc-2-requirements.sdoc b/docs/strictdoc-3-requirements.sdoc similarity index 93% rename from docs/strictdoc-2-requirements.sdoc rename to docs/strictdoc-3-requirements.sdoc index dcfd5b083..ce2c26e53 100644 --- a/docs/strictdoc-2-requirements.sdoc +++ b/docs/strictdoc-3-requirements.sdoc @@ -422,35 +422,3 @@ Source coverage screen shows how source files are linked with requirements. <<< [/SECTION] - -[SECTION] -TITLE: Design decisions - -[SECTION] -TITLE: Building blocks - -[REQUIREMENT] -TITLE: TextX -STATEMENT: TextX shall be used for StrictDoc grammar definition and parsing of the sdoc files. -COMMENT: >>> -TextX is an easy-to-install Python tool. It is fast, works out of the box. -<<< - -[REQUIREMENT] -TITLE: Jinja2 -STATEMENT: Jinja2 shall be used for rendering HTML templates. - -[REQUIREMENT] -TITLE: Sphinx and Docutils -STATEMENT: >>> -Sphinx and Docutils shall be used for the following capabilities: - -- Support of Restructured Text (reST) format -- Generation of RST documents into HTML -- Generation of RST documents into PDF using LaTeX -- Generating documentation websites using Sphinx -<<< - -[/SECTION] - -[/SECTION] diff --git a/docs/strictdoc-4-design.sdoc b/docs/strictdoc-4-design.sdoc new file mode 100644 index 000000000..0894b9c49 --- /dev/null +++ b/docs/strictdoc-4-design.sdoc @@ -0,0 +1,36 @@ +[DOCUMENT] +TITLE: StrictDoc Design Document +OPTIONS: + REQUIREMENT_STYLE: Inline + +[SECTION] +TITLE: Design decisions + +[SECTION] +TITLE: Building blocks + +[REQUIREMENT] +TITLE: TextX +STATEMENT: TextX shall be used for StrictDoc grammar definition and parsing of the sdoc files. +COMMENT: >>> +TextX is an easy-to-install Python tool. It is fast, works out of the box. +<<< + +[REQUIREMENT] +TITLE: Jinja2 +STATEMENT: Jinja2 shall be used for rendering HTML templates. + +[REQUIREMENT] +TITLE: Sphinx and Docutils +STATEMENT: >>> +Sphinx and Docutils shall be used for the following capabilities: + +- Support of Restructured Text (reST) format +- Generation of RST documents into HTML +- Generation of RST documents into PDF using LaTeX +- Generating documentation websites using Sphinx +<<< + +[/SECTION] + +[/SECTION] diff --git a/docs/strictdoc-4-backlog.sdoc b/docs/strictdoc-5-backlog.sdoc similarity index 99% rename from docs/strictdoc-4-backlog.sdoc rename to docs/strictdoc-5-backlog.sdoc index 564b18969..b06e21433 100644 --- a/docs/strictdoc-4-backlog.sdoc +++ b/docs/strictdoc-5-backlog.sdoc @@ -22,7 +22,7 @@ COMMENT: The current plan is to implement this using ReqIF export/import feature UID: BACKLOG-LSP REFS: - TYPE: Parent - VALUE: FRONTEND-1-TEXT + VALUE: UI-1-TEXT TITLE: SDoc Language Server Protocol STATEMENT: >>> StrictDoc shall support Language Server Protocol. @@ -189,7 +189,7 @@ Several trade-offs to consider: UID: BACKLOG-WEB REFS: - TYPE: Parent - VALUE: FRONTEND-2-WEB + VALUE: UI-2-WEB TITLE: Web server and editable HTML pages STATEMENT: >>> StrictDoc shall provide a web server that serves as a StrictDoc backend for diff --git a/docs/strictdoc-html/strictdoc-html/_static/_requirement.css b/docs/strictdoc-html/strictdoc-html/_static/_requirement.css index c6a128eff..d8fa3f8cd 100644 --- a/docs/strictdoc-html/strictdoc-html/_static/_requirement.css +++ b/docs/strictdoc-html/strictdoc-html/_static/_requirement.css @@ -71,6 +71,11 @@ article > section:last-of-type { padding-bottom: var(--base-padding); } +.document-view article > section { + padding-left: 0; + padding-right: 0; +} + /* .table-view */ .table-view section, @@ -494,3 +499,46 @@ input:checked + .std-switch_slider:before { .requirements-coverage-document-title:first-child { margin-top: -1rem; } + +/* requirement-table */ + +.requirement-table { + border-collapse: collapse; + width: 100%; +} + +.requirement-table caption { + text-align: left; + background-color: var(--color-bg-main); + margin-bottom: -1px; + font-size: 1.2em; +} + +.requirement-table th { + background-color: #fff; + text-align: left; + font-weight: normal; + text-transform: uppercase; + font-family: 'Courier New', Courier, monospace; + width: 10%; +} + +.requirement-table td, +.requirement-table th, +.requirement-table caption { + padding: .5rem 1rem; + border: 1px solid #666; +} + +.requirement-table ul.requirement_link:first-child, +.requirement-table p:first-child { + margin-top: 0; +} +.requirement-table ul.requirement_link:last-child, +.requirement-table p:last-child { + margin-bottom: 0; +} + +.requirement-table ul.requirement_link { + font-size: 1em; +} diff --git a/docs/strictdoc-html/strictdoc-html/docs/strictdoc-3-development-plan-DEEP-TRACE.html b/docs/strictdoc-html/strictdoc-html/docs/strictdoc-2-development-plan-DEEP-TRACE.html similarity index 93% rename from docs/strictdoc-html/strictdoc-html/docs/strictdoc-3-development-plan-DEEP-TRACE.html rename to docs/strictdoc-html/strictdoc-html/docs/strictdoc-2-development-plan-DEEP-TRACE.html index 1cc1f1a54..abc516c51 100644 --- a/docs/strictdoc-html/strictdoc-html/docs/strictdoc-3-development-plan-DEEP-TRACE.html +++ b/docs/strictdoc-html/strictdoc-html/docs/strictdoc-2-development-plan-DEEP-TRACE.html @@ -66,15 +66,15 @@ 1.4 Change management -
  • +
  • 2 - Two frontends + User interfaces
  • @@ -91,25 +91,25 @@ + href="../docs/strictdoc-2-development-plan.html"> DOC + href="../docs/strictdoc-2-development-plan-TABLE.html"> TBL + href="../docs/strictdoc-2-development-plan-TRACE.html"> TR + href="../docs/strictdoc-2-development-plan-DEEP-TRACE.html"> DTR @@ -176,7 +176,7 @@