Merge pull request #694 from strictdoc-project/too-long-command-windows

 docs: update documentation, introduce design document

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

docs/sphinx/source/strictdoc-3-development-plan.rst → 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,16 +127,16 @@ Text frontend
     * - **UID:**
       - FRONTEND-1-TEXT
 
-...
+StrictDoc shall provide a command-line interface.
 
 **Children:**
 
 - ``[BACKLOG-LSP]`` :ref:`BACKLOG-LSP`
 
 .. _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.
 

docs/sphinx/source/strictdoc-2-requirements.rst → 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
-

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
+

docs/strictdoc-3-development-plan.sdoc → 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]
 

docs/strictdoc-2-requirements.sdoc → docs/strictdoc-3-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.
 
@@ -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]

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]

docs/strictdoc-4-backlog.sdoc → 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

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;
+}