Merge pull request strictdoc-project#1950 from strictdoc-project/stan…

…islaw/docs docs: migrate all FREETEXT to TEXT
haxtibal · Oct 13, 2024 · f3e7783 · f3e7783
2 parents 05aa879 + a9af1e1
commit f3e7783
Show file tree

Hide file tree

Showing 11 changed files with 501 additions and 335 deletions.
diff --git a/docs/strictdoc_01_user_guide.sdoc b/docs/strictdoc_01_user_guide.sdoc
diff --git a/docs/strictdoc_02_faq.sdoc b/docs/strictdoc_02_faq.sdoc
@@ -5,29 +5,32 @@ OPTIONS:
   REQUIREMENT_STYLE: Inline
   REQUIREMENT_IN_TOC: True
 
-[FREETEXT]
+[TEXT]
+STATEMENT: >>>
 This document is a list of questions that people ask about StrictDoc.
 
 Missing a question or an answer? Ask it here: [LINK: SDOC_UG_CONTACT].
-[/FREETEXT]
+<<<
 
 [SECTION]
 TITLE: What is StrictDoc?
 
-[FREETEXT]
+[TEXT]
+STATEMENT: >>>
 StrictDoc is software for writing technical requirements specifications.
 
 StrictDoc is a spare-time open-source project developed by Stanislav Pankevich (@stanislaw) and Maryna Balioura (@mettta) with contributions from the Open Source community.
 
 The project exists since mid-2019.
-[/FREETEXT]
+<<<
 
 [/SECTION]
 
 [SECTION]
 TITLE: Resources about StrictDoc
 
-[FREETEXT]
+[TEXT]
+STATEMENT: >>>
 Talks:
 
 - `Application of the SPDX Safety Profile in the Safety Scope of the Zephyr Project <https://mirrors.dotsrc.org/fosdem/2024/k4401/fosdem-2024-3211-application-of-the-spdx-safety-profile-in-the-safety-scope-of-the-zephyr-project.mp4>`_. This presentation introduces the SPDX Safety Profile and details its application within the context of the Zephyr Project. There is also a presentation of the Zephyr project's methodology for capturing requirements using StrictDoc and a discussion of the upcoming plans for the integration of SPDX into StrictDoc.
@@ -43,14 +46,15 @@ Screencasts/tutorials:
 - `Automotive SPICE in opensource StrictDoc tool, with System Architecure ideas
   <https://www.youtube.com/watch?v=k2MCFWvCs7E>`_
   by Lukasz Juranek.
-[/FREETEXT]
+<<<
 
 [/SECTION]
 
 [SECTION]
 TITLE: Which web server is recommended for StrictDoc documentation?
 
-[FREETEXT]
+[TEXT]
+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.
 
 The following suggestions assume that you are looking to using a web server to host the StrictDoc's static HTML export, without using StrictDoc's own web server.
@@ -60,14 +64,15 @@ Is your project public or private? If it is public, you could simply use `GitHub
 A very good alternative to GitHub pages is `Read the Docs <https://readthedocs.org>`_.
 
 If the project is private, you could use any server that reads HTML files from a folder. For example, Python has an embedded Web Server, see `this for example <https://pythonbasics.org/webserver>`_. Also you could try any web server based on Node.JS.
-[/FREETEXT]
+<<<
 
 [/SECTION]
 
 [SECTION]
 TITLE: Is StrictDoc compatible with Sphinx?
 
-[FREETEXT]
+[TEXT]
+STATEMENT: >>>
 StrictDoc is only partially compatible with Sphinx.
 
 StrictDoc does not have Sphinx in its dependency tree, and it does not use any of Sphinx API. Instead, StrictDoc uses Docutils for RST markup support. Using Docutils, StrictDoc can generate SDoc files to RST files.
@@ -80,14 +85,15 @@ There are users of StrictDoc who use both StrictDoc and Sphinx. The following wo
 - Run Sphinx against an RST documentation tree, obtain a Sphinx documentation website or LaTex PDF.
 
 There is a GitHub issue `Unexpected restriction on specific RST directives / compatibility with Breathe Sphinx Plugin #1093 <https://github.com/strictdoc-project/strictdoc/issues/1093>`_ where a closer bridging between StrictDoc and Sphinx was discussed with no specific and actionable outcome. This comment is `especially relevant <https://github.com/strictdoc-project/strictdoc/issues/1093#issuecomment-1505108384>`_ as well as the one about `possible implementation <https://github.com/strictdoc-project/strictdoc/issues/1093#issuecomment-1545599711>`_.
-[/FREETEXT]
+<<<
 
 [/SECTION]
 
 [SECTION]
 TITLE: How did the SDoc text language become what it is?
 
-[FREETEXT]
+[TEXT]
+STATEMENT: >>>
 Shortly: The SDoc markup is a hybrid of TOML and YAML with some influence from HTML/XML and `ASN.1 <https://en.wikipedia.org/wiki/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.
 
 ----
@@ -168,7 +174,7 @@ The support of multiline strings is arranged by a custom solution which helps to
 **Discarded options**
 
 Taking TOML or YAML as-is didn't seem like a good option because these formats are designed to be used for configuration files or data serialization and not for large documents with hundreds of requirements. The most obvious problems for reusing either of TOML or YAML directly would have been with encoding the deeply nested documents and supporting readable and non-nested multiline strings.
-[/FREETEXT]
+<<<
 
 [/SECTION]
 
@@ -178,7 +184,8 @@ TITLE: How StrictDoc compares to other tools?
 [SECTION]
 TITLE: Doorstop
 
-[FREETEXT]
+[TEXT]
+STATEMENT: >>>
 The StrictDoc project is a close successor of another project called
 `Doorstop <https://github.com/doorstop-dev/doorstop>`_.
 
@@ -226,14 +233,15 @@ StrictDoc differs from Doorstop in a number of aspects:
 
 The roadmap of StrictDoc contains a work item for supporting the export/import
 to/from Doorstop format.
-[/FREETEXT]
+<<<
 
 [/SECTION]
 
 [SECTION]
 TITLE: Sphinx
 
-[FREETEXT]
+[TEXT]
+STATEMENT: >>>
 Both Sphinx and StrictDoc are both documentation generators but StrictDoc is at
 a higher level of abstraction: StrictDoc's specialization is requirements and
 specifications documents. StrictDoc can generate documentation to a number of
@@ -250,14 +258,15 @@ is converted to RST format by StrictDoc which is further converted to the HTML
 website by readthedocs which uses Sphinx under the hood. The
 ``StrictDoc -> RST -> Sphinx -> PDF`` example is also generated using readthedocs:
 `StrictDoc <https://strictdoc.readthedocs.io/_/downloads/en/latest/pdf/>`_.
-[/FREETEXT]
+<<<
 
 [/SECTION]
 
 [SECTION]
 TITLE: Sphinx-Needs
 
-[FREETEXT]
+[TEXT]
+STATEMENT: >>>
 `Sphinx-Needs <https://sphinxcontrib-needs.readthedocs.io/en/latest/>`_ is a
 text-based requirements management system based on Sphinx. It is implemented
 as a Sphinx extension which extends the
@@ -310,14 +319,15 @@ The difference between Sphinx-Needs and StrictDoc:
   and
   `others
   <https://sphinxcontrib-needs.readthedocs.io/en/latest/index.html>`_.
-[/FREETEXT]
+<<<
 
 [/SECTION]
 
 [SECTION]
 TITLE: FRET
 
-[FREETEXT]
+[TEXT]
+STATEMENT: >>>
 `FRET <https://github.com/NASA-SW-VnV/fret>`_ is a framework for the
 elicitation, specification, formalization and understanding of requirements.
 
@@ -334,7 +344,7 @@ FRET has an impressive list of
 FRET's user interface is built with Electron.
 
 The detailed comparison is coming.
-[/FREETEXT]
+<<<
 
 [/SECTION]
 
@@ -343,7 +353,8 @@ The detailed comparison is coming.
 [SECTION]
 TITLE: How long has the StrictDoc project been around?
 
-[FREETEXT]
+[TEXT]
+STATEMENT: >>>
 The first StrictDoc commit dates back to ``2019-08-10``. A short development chronology of StrictDoc is as follows:
 
 **2019 – July – August**
@@ -372,20 +383,21 @@ The custom RST parser was replaced with a TextX-based DSL. Since then, StrictDoc
 **2022 – November**
 
 The FastAPI/Turbo/Stimulus-based Web interface prototype was created to complement the text-based interface with a graphical user interface (GUI). When the Web-based GUI is stable, StrictDoc may become useable by non-programmers too.
-[/FREETEXT]
+<<<
 
 [/SECTION]
 
 [SECTION]
 TITLE: Which StrictDoc statistics are available?
 
-[FREETEXT]
+[TEXT]
+STATEMENT: >>>
 Most relevant GitHub statistics:
 
 - `Contributors <https://github.com/strictdoc-project/strictdoc/graphs/contributors>`_
 
 The `pip trends <https://piptrends.com>`_ helps to visualize the Pip package download stats. The ``reqif`` satellite project is included for comparison as well:
 `strictdoc vs reqif <https://piptrends.com/compare/strictdoc-vs-reqif>`_.
-[/FREETEXT]
+<<<
 
 [/SECTION]
diff --git a/docs/strictdoc_03_development_plan.sdoc b/docs/strictdoc_03_development_plan.sdoc
@@ -4,15 +4,17 @@ OPTIONS:
   REQUIREMENT_STYLE: Table
   REQUIREMENT_IN_TOC: True
 
-[FREETEXT]
+[TEXT]
+STATEMENT: >>>
 This document presents the goals of the StrictDoc project and describes how the
 project is developed.
-[/FREETEXT]
+<<<
 
 [SECTION]
 TITLE: Project goals
 
-[FREETEXT]
+[TEXT]
+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.
 
 **Requirements automation**
@@ -34,7 +36,7 @@ An important feature of StrictDoc is its focus on open data, ensuring ease of da
 **Synergies with other tools**
 
 StrictDoc shall be compatible with other software and engineering tools. This includes at least the compatibility with the Python ecosystem, the model-based systems engineering tools, such as Capella, and the formats providing Software Bill of Materials, such as SPDX.
-[/FREETEXT]
+<<<
 
 [/SECTION]
 
@@ -101,15 +103,15 @@ As an open-source project, StrictDoc is developed without strict deadlines, howe
 [SECTION]
 TITLE: The roadmap diagram
 
-[FREETEXT]
+[TEXT]
+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.
 
 .. image:: _assets/StrictDoc_Workspace-Roadmap.drawio.png
    :alt: Development plan diagram
    :class: image
    :width: 100%
-
-[/FREETEXT]
+<<<
 
 [/SECTION]
 
@@ -118,27 +120,29 @@ The following diagram contains the work items at the epic and single task levels
 [SECTION]
 TITLE: Verification
 
-[FREETEXT]
+[TEXT]
+STATEMENT: >>>
 StrictDoc has three groups of tests: unit, integration, end-to-end tests.
 
 The unit tests are based on Pylint.
 
 The integration tests are based on the `LLVM Integrated Tester <https://llvm.org/docs/CommandGuide/lit.html>`_ and `FileCheck.py <https://github.com/mull-project/FileCheck.py/blob/main/pyproject.toml>`_. These tools are not very common, refer to `How to test command-line programs with Python tools: LIT and FileCheck <https://stanislaw.github.io/2020-11-20-how-to-test-command-line-programs-with-python.html>`_ for a good description.
 
 The end-to-end web interface tests are based on SeleniumBase test framework.
-[/FREETEXT]
+<<<
 
 [/SECTION]
 
 [SECTION]
 TITLE: Python baseline
 
-[FREETEXT]
+[TEXT]
+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.
 
 Ideally, the lowest Python version should only be raised when it is consistently deprecated by the major software platforms like Ubuntu or GitHub Actions.
 
 Another reason for upgrading the minimum Python version is due to the upstream dependencies. As these dependencies stop supporting the older versions of Python, StrictDoc must be upgraded to maintain compatibility. With the existing dependency graph, this happens rather infrequently as most dependencies also maintain the compatibility with the older Python versions.
-[/FREETEXT]
+<<<
 
 [/SECTION]