2.1.0

quantum-leaps · quantum-leaps · commit 9f98e99cc37f · 2024-07-15T15:37:23.000-04:00
improved forward traceability generation
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,4 @@
 spexygen.tar.gz
+
 html/
+spexy/
diff --git a/Spexyfile b/Spexyfile
@@ -37,8 +37,6 @@ ALIASES += \
 #---------------------------------------------------------------------------
 # Spexygen: spexygen-awesome style
 #---------------------------------------------------------------------------
-HTML_HEADER            = $(SPEXYGEN)/spexygen-awesome/spexy-header.html
-HTML_FOOTER            = $(SPEXYGEN)/spexygen-awesome/spexy-footer.html
 HTML_EXTRA_STYLESHEET  = $(SPEXYGEN)/spexygen-awesome/doxygen-awesome.css \
                          $(SPEXYGEN)/spexygen-awesome/doxygen-awesome-sidebar-only.css \
                          $(SPEXYGEN)/spexygen-awesome/doxygen-awesome-sidebar-only-darkmode-toggle.css \
@@ -48,10 +46,18 @@ HTML_EXTRA_FILES       = $(SPEXYGEN)/spexygen-awesome/doxygen-awesome-darkmode-t
                          $(SPEXYGEN)/spexygen-awesome/doxygen-awesome-paragraph-link.js \
                          $(SPEXYGEN)/spexygen-awesome/image-preview.js
 
+#---------------------------------------------------------------------------
+# Spexygen: customized HTML header/footer
+# (can be overridden by the including Doxyfile)
+#---------------------------------------------------------------------------
+HTML_HEADER            = $(SPEXYGEN)/spexygen-awesome/spexy-header.html
+HTML_FOOTER            = $(SPEXYGEN)/spexygen-awesome/spexy-footer.html
+
 #---------------------------------------------------------------------------
 # Configuration options related to the LaTeX output
 #---------------------------------------------------------------------------
-# Spexygen: customized LaTeX formatting
+# Spexygen: customized LaTeX header/footer
+# (can be overridden by the including Doxyfile)
 #---------------------------------------------------------------------------
 LATEX_HEADER           = $(SPEXYGEN)/spexygen-awesome/spexy-header.tex
 LATEX_FOOTER           = $(SPEXYGEN)/spexygen-awesome/spexy-footer.tex
diff --git a/doc/DOC_MAN_SPX.pdf b/doc/DOC_MAN_SPX.pdf
diff --git a/doc/Doxyfile b/doc/Doxyfile
@@ -6,7 +6,7 @@
 # Project related configuration options
 #---------------------------------------------------------------------------
 PROJECT_NAME           = Spexygen
-PROJECT_NUMBER         = 2.0.1
+PROJECT_NUMBER         = 2.1.0
 PROJECT_BRIEF          = "Reference Manual"
 PROJECT_LOGO           = ./img/logo_spexygen.webp
 PROJECT_ICON           =
diff --git a/doc/Doxyfile-PDF b/doc/Doxyfile-PDF
@@ -6,7 +6,7 @@
 # Configuration options related to the LateX output
 #---------------------------------------------------------------------------
 PROJECT_NAME           = Reference Manual
-PROJECT_BRIEF          = For Spexygen 2.0.1
+PROJECT_BRIEF          = For Spexygen 2.1.0
 PROJECT_NUMBER         = Document: DOC_MAN_SPX
 
 #---------------------------------------------------------------------------
diff --git a/example/exa.dox b/example/exa.dox
@@ -4,18 +4,12 @@
 <div style="clear:both"></div>
 @endif
 
-The _spexygen_ distribution contains an example for generating traceable documentation with _spexygen_. The example is located in the @webref{https://github.com/QuantumLeaps/spexygen/tree/main/example,spexygen/example} folder, with the following content:
+The _Spexygen_ distribution contains an example for generating traceable documentation with _Spexygen_. The example is located in the @webref{https://github.com/QuantumLeaps/Spexygen/tree/main/example,spexygen/example} folder, with the following content:
 
 @code{c}
 spexygen/
-|   LICENSE
-|   README.md
-|   Spexyfile
-|   spexygen.py
 |
-+---doc/
-|
-+---example/     <-- spexygen example
++---example/     <-- Spexygen example
 |   |   exa.dox  <-- example description
 |   |   dev.dox  <-- example traceable deviations from coding standards
 |   |   srs.dox  <-- example traceable Software Requirements Specification
@@ -29,12 +23,10 @@ spexygen/
 |   \---test
 |           test1.c  <-- example test file
 |           test2.c  <-- example test file
-|
-\---spexygen-awesome/
  @endcode
 
 @section exa_gen Spexygen-Generated Documentation
-The following sections contain the _spexygen_-generated documentation of this example:
+The following sections contain the _Spexygen_-generated documentation of this example:
 - @subpage srs
 - @subpage dev
 - @ref header.h
@@ -43,7 +35,7 @@ The following sections contain the _spexygen_-generated documentation of this ex
 - @ref test2.c
 
 @note
-Please note the generated @ref tr-fw "forward-traceability" and the @ref tr-bw "backward-traceability" links (augmented with the brief descriptions) in the @ref spx_use-doc-uid "work artifacts" and @ref spx_use-doc-code "code artifacts". Also, try clicking on the provided traceability links as well as __searching__ the @ref tr-uid "UIDs" in the doxygen "search" box.
+Please note the generated @ref tr-fw "forward-traceability" and the @ref tr-bw "backward-traceability" links (augmented with the brief descriptions) in the @ref spx_use-doc-uid "work artifacts" and @ref spx_use-doc-code "code artifacts". Also, try clicking on the provided traceability links as well as __searching__ the @ref tr-uid "UIDs" in the Doxygen "search" box.
 
 <p></p>
 @ifnot LATEX
diff --git a/example/inc/header.h b/example/inc/header.h
@@ -35,20 +35,20 @@ Class Foo longer description.
 typedef struct Foo {
     /*! @code_uid{Foo::x, Attribute x of class Foo brief description}
     @code_litem{Details}
-    Attribute x of class Foo longer description.
-
+    Attribute x of class Foo: longer description.
     @code_bw_trace{brief}
     - @tr{SRS_PRJ_Foo_01}
     @endcode_uid
     */
     uint32_t x;
 
-    /*! @code_uid{Foo::x_dis, protection for attribute Foo::x brief description}
+    /*! @code_uid{Foo::x_dis, Duplicate Inverse Storage for attribute Foo::x}
     @code_litem{Details}
-    Duplicate Inverse Storage (DIS) for attribute Foo::x longer description.
-
+    Duplicate Inverse Storage (DIS) for attribute Foo::x: longer description.
     @code_bw_trace{brief}
     - @tr{SRS_PRJ_Foo_01}
+    - @tr{Foo_verify_()}
+    - @tr{Foo::x}
     @endcode_uid
     */
     uint32_t x_dis;
@@ -58,42 +58,56 @@ typedef struct Foo {
 @code_uid{Foo_inst, Foo instance brief description}
 @code_litem{Details}
 Foo instance longer description.
-
 @code_bw_trace{brief}
 - @tr{SRS_PRJ_Foo_04}
+- @tr{Foo}
 - @tr{DVP_PRJ_MC4_R11_03}
 @code_fw_trace
 @endcode_uid
 */
 extern Foo const Foo_inst;
 
 /*!
-@code_uid{Foo_ctor(), Constructor of class Foo brief description}
+@code_uid{Foo_update_(), Update operation to preserve the class invariant}
 @code_litem{Details}
 Constructor of class Foo longer description.
+@param[in]  me - the instance pointer (OOP in C)
+@code_bw_trace{brief}
+- @tr{SRS_PRJ_Foo_02}
+- @tr{Foo}
+@code_fw_trace
+@endcode_uid
+*/
+static inline void Foo_update_(Foo* const me) {
+    me->x_dis = ~(uintptr_t)me->x;
+}
 
+/*!
+@code_uid{Foo_ctor(), Constructor of class Foo brief description}
+@code_litem{Details}
+Constructor of class Foo longer description.
 @param[in]  me - the instance pointer (OOP in C)
 @param[in]  x  - the initial value for me->x
-
 @code_bw_trace{brief}
 - @tr{SRS_PRJ_Foo_02}
+- @tr{Foo}
 @code_fw_trace
 @endcode_uid
 */
 static inline void Foo_ctor(Foo * const me, uint32_t const x) {
     me->x = x;
-    me->x_dis = ~(uintptr_t)me->x;
+    Foo_update_(me);
 }
 
 /*!
 @code_uid{Foo_verify_(), Operation verify_() of class Foo brief description}
 @code_litem{Details}
 Operation verify_() of class Foo longer description.
-
 @param[in]  me - the instance pointer (OOP in C)
-
+@returns 'true' when the Foo instance verification succeeds, 'false' otherwise.
 @code_bw_trace{brief}
 - @tr{SRS_PRJ_Foo_03}
+- @tr{Foo}
 @code_fw_trace
 @endcode_uid
 */
diff --git a/example/srs.dox b/example/srs.dox
@@ -5,13 +5,13 @@
 @endif
 
 @remark
-This is an example Software Requirements Specification (SRS), illustrating the typical structure and the use of _spexygen_ commands to define the @ref tr "traceable" requirement work artifacts.
+This is an example Software Requirements Specification (SRS), illustrating the typical structure and the use of _Spexygen_ commands to define the @ref tr "traceable" requirement work artifacts.
 
 @section srs-def Concepts &amp; Definitions
 Description of concepts and definitions...
 
 @section srs_req Requirements
-Definitions of formal requirements specifications with _spexygen_ commands...
+Definitions of formal requirements specifications with _Spexygen_ commands...
 
 @uid{SRS_PRJ_FF_00,My project shall provide a free function foo().}
 @uid_litem{Description}
diff --git a/example/test/test1.c b/example/test/test1.c
@@ -11,7 +11,6 @@ void tearDown(void) {
 @code_uid{TUN_PRJ_free_fun_00, zero input test}
 @code_litem{Details}
 This test checks that zero input to free_fun() produces zero array.
-
 @code_bw_trace{brief}
 - @tr{free_fun()}
 @endcode_uid
@@ -29,7 +28,6 @@ void TUN_PRJ_free_fun_00(void) {
 @code_uid{TUN_PRJ_free_fun_01, non-zero input}
 @code_litem{Details}
 This test checks that non-zero input to free_fun() produces expected array.
-
 @code_bw_trace
 - @tr{free_fun()}
 @endcode_uid
diff --git a/example/test/test2.c b/example/test/test2.c
@@ -9,10 +9,8 @@ void tearDown(void) {
 
 /*!
 @code_uid{TUN_PRJ_Foo_ctor_01, constructor test}
-
 @code_litem{Details}
 This test checks that Foo_ctor() produces valid instance.
-
 @code_bw_trace{brief}
 - @tr{Foo_ctor()}
 @endcode_uid
@@ -26,10 +24,8 @@ void TUN_PRJ_Foo_ctor_01(void) {
 
 /*!
 @code_uid{TUN_PRJ_Foo_verify_00, verify positive test}
-
 @code_litem{Details}
 This test checks that Foo_verify_() distinguishes valid instance.
-
 @code_bw_trace{brief}
 - @tr{Foo_verify_()}
 @endcode_uid
@@ -41,10 +37,8 @@ void TUN_PRJ_Foo_verify_00(void) {
 
 /*!
 @code_uid{TUN_PRJ_Foo_verify_01, verify negative test}
-
 @code_litem{Details}
 This test checks that Foo_verify_() distinguishes invalid instance.
-
 @code_bw_trace{brief}
 - @tr{Foo_verify_()}
 @endcode_uid
diff --git a/setup.py b/setup.py
@@ -9,7 +9,7 @@
 
 setup(
     name="spexygen",
-    version="2.0.1",
+    version="2.1.0",
     author="Quantum Leaps",
     author_email="info@state-machine.com",
     description="Traceable specifications based on doxygen",
diff --git a/spexygen-awesome/help.dox b/spexygen-awesome/help.dox
@@ -0,0 +1,46 @@
+/*!
+@ifnot LATEX
+
+@page help Using Online Help
+
+<p>You can use this online help in various ways: either sequentially from beginning to end or just by quickly locating the interesting topic.
+</p>
+
+[![](help_using.jpg)](https://github.com/QuantumLeaps/spexygen)
+@caption{Online Help Features}
+
+@section help_dark_mode Dark Mode Toggle
+You can toggle the Dark/Light Mode of the help display with the button in the top-left corner, below the logo.
+
+<img src="help_light.webp" style="float:left; margin-right:10px;">
+The Light display mode is selected
+
+<img src="help_dark.webp" style="float:left; margin-right:10px;">
+The Dark display mode is selected
+
+@section help_tree_view Using the Tree View
+The *Tree View* pane on the left-hand side of the browser displays the hierarchical Table of Contents, which can be either **linked-to** or **unlinked-from** the *Current Topic* displayed on the right-hand side. You can toggle between the two modes by pressing the **Link/Unlink Current Topic** icon at the top of the *Tree View* pane.
+
+<img src="tree-view_linked.webp" style="float:left; margin-right:10px;">
+When the *Tree View* is **linked** to the Current Topic, the *Tree View* will always follow the currently viewed topic, by expanding and highlighting the pertinent section of the hierarchical Table of Contents.
+
+<div style="clear:both;"></div>
+<img src="tree-view_unlinked.webp" style="float:left; margin-right:10px;">
+When the *Tree View* is **unlinked** from the Current Topic, the *Tree View* will show only the explicitly selected section of the hierarchical Table of Contents and will **not** follow the topics activated by internal documentation links.
+
+@section help_seq Reading Online Help Sequentially
+You can move from topic to topic by means of the <span class="strong underline">Next:</span> link at the bottom of each page.
+
+@section help_random Quickly Locating a Topic of Interest
+You can use the following elements:
+- the @ref help_tree_view "Tree View" pane on the left-hand side of the browser;
+- the **Table of Contents** box in the top-right corner of the page;
+- the **Search** box in the upper-right corner of the browser window
+
+@section hel_spexygen Spexygen on GitHub
+If you like this styling for doxygen, it is based on @webref{https://github.com/jothepro/doxygen-awesome-css,doxygen-awesome-css}. The styling with modifications made by Quantum Leaps is available as part of the @webref{https://github.com/QuantumLeaps/spexygen,spexyen documentation system}.
+
+[![Spexygen on GitHub](logo_spexygen.webp)](https://github.com/QuantumLeaps/spexygen)
+
+@endif
+*/
diff --git a/spexygen.py b/spexygen.py

-Original file line number
+Diff line change
@@ @@ -1,2 +1,4 @@ @@
 spexygen.tar.gz
++
 html/
 +spexy/