Skip to content

Commit 70ca9d1

Browse files
PaebbelsPaebbels
committed
Added more documentation
1 parent 4f5b03b commit 70ca9d1

15 files changed

Lines changed: 359 additions & 47 deletions

File tree

‎.github/workflows/Pipeline.yml‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -207,16 +207,16 @@ jobs:
207207
html_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_html }}
208208
latex_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_latex }}
209209

210-
PDFDocumentation:
211-
uses: pyTooling/Actions/.github/workflows/LaTeXDocumentation.yml@r4
212-
needs:
213-
- ConfigParams
214-
- UnitTestingParams
215-
- Documentation
216-
with:
217-
document: ${{ needs.ConfigParams.outputs.package_fullname }}
218-
latex_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_latex }}
219-
pdf_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_pdf }}
210+
# PDFDocumentation:
211+
# uses: pyTooling/Actions/.github/workflows/LaTeXDocumentation.yml@r4
212+
# needs:
213+
# - ConfigParams
214+
# - UnitTestingParams
215+
# - Documentation
216+
# with:
217+
# document: ${{ needs.ConfigParams.outputs.package_fullname }}
218+
# latex_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_latex }}
219+
# pdf_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_pdf }}
220220

221221
PublishToGitHubPages:
222222
uses: pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml@r4

‎doc/CodeCoverage.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _CODECOV:
2+
13
Code Coverage Report
24
####################
35

‎doc/ConfigurationFile.rst‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
.. _CONFIG:
2+
3+
Configuration File
4+
##################
5+
6+
:file:`.pyVersioning.yaml`
7+
8+
.. card:: .pyVersioning.yaml
9+
10+
.. code-block:: YAML
11+
12+
version: 1
13+
14+
project:
15+
name: Test Project
16+
variant: A2
17+
version: v2.1.6
18+
19+
build:
20+
compiler:
21+
name: gcc
22+
version: 10.2.0
23+
configuration: Release
24+
options: -g -O3

‎doc/DocCoverage.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _DOCCOV:
2+
13
Documentation Coverage Report
24
#############################
35

‎doc/Examples/C.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,18 @@
1+
.. _EXAMPLES/C:
2+
13
ANSI-C
24
######
35

6+
.. _EXAMPLES/C/ConfigFile:
7+
48
YAML Configuration File
59
***********************
610

711
.. literalinclude:: ../../example/C/.pyVersioning.yml
812
:language: YAML
913

14+
.. _EXAMPLES/C/Application:
15+
1016
C Example Application
1117
*********************
1218

‎doc/Examples/CXX.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,18 @@
1+
.. _EXAMPLES/CXX:
2+
13
C++
24
###
35

6+
.. _EXAMPLES/CXX/ConfigFile:
7+
48
YAML Configuration File
59
***********************
610

711
.. literalinclude:: ../../example/CXX/.pyVersioning.yml
812
:language: YAML
913

14+
.. _EXAMPLES/CXX/Application:
15+
1016
C++ Example Application
1117
***********************
1218

‎doc/Examples/VHDL.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,6 @@
1+
.. _EXAMPLES/VHDL:
2+
13
VHDL
24
####
5+
6+
.. todo:: Add a VHDL example.

‎doc/Templates/C.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,17 @@
1+
.. _TEMPLATE/C:
2+
13
ANSI-C
24
######
35

6+
.. _TEMPLATE/C/Header:
7+
48
C Header File
59
*************
610

711
.. literalinclude:: ../../templates/C/versioning.h
812
:language: C
913

14+
.. _TEMPLATE/C/Template:
1015

1116
C Template File
1217
***************

‎doc/Templates/CXX.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,17 @@
1+
.. _TEMPLATE/CXX:
2+
13
C++
24
###
35

6+
.. _TEMPLATE/CXX/Header:
7+
48
C++ Header File
59
***************
610

711
.. literalinclude:: ../../templates/CXX/versioning.hpp
812
:language: C++
913

14+
.. _TEMPLATE/CXX/Template:
1015

1116
C++ Template File
1217
*****************

‎doc/Templates/index.rst‎

Lines changed: 210 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,214 @@
1+
.. _TEMPLATES:
2+
13
Writing Templates
24
#################
35

4-
.. todo:: Explain syntax used by Python's ``str.format()``.
6+
.. _TEMPLATES/Syntax:
7+
8+
Syntax
9+
******
10+
11+
The used template format is based on Python's :meth:`str.format` method. Thus a list of predefined variables can be
12+
embedded into a text using ``{myVariable}`` syntax. As curley braces are used to denote variables, double curley
13+
braces will translate to curley braces in the output text, e.g. needed in C-like languages: ``{{`` |rarr| ``{`` or
14+
``}}`` |rarr| ``}``.
15+
16+
.. card:: myTemplate.c.template
17+
18+
.. code-block:: C
19+
20+
typedef struct {{
21+
.field = "{myVariable}"
22+
}} myExample;
23+
24+
.. _TEMPLATES/Syntax/Member:
25+
26+
Member Access
27+
=============
28+
29+
A variable member can be accessed using the dot-notation.
30+
31+
.. card:: myTemplate.c.template
32+
33+
.. code-block:: C
34+
35+
typedef struct {{
36+
.field = "{myVariable.myProperty}"
37+
}} myExample;
38+
39+
.. _TEMPLATES/Syntax/Method:
40+
41+
Method Access
42+
=============
43+
44+
A variable's method can be accessed using the dot-notation.
45+
46+
.. card:: myTemplate.c.template
47+
48+
.. code-block:: C
49+
50+
typedef struct {{
51+
.field = "{myVariable.myMethod()}"
52+
}} myExample;
53+
54+
.. _TEMPLATES/Syntax/Formatting:
55+
56+
Formatting
57+
==========
58+
59+
The :ref:`Pyton string formating <string-formatting>` syntax allows for further :ref:`customizations <formatspec>` like left, middle or
60+
right justification as well as number formating e.g. as hex-values.
61+
62+
.. rubric:: Examples
63+
64+
``{myVariable:\0<16}``
65+
Left justified 16-character string padded with ``\0``.
66+
``0x{myVariable:02X}``
67+
Zero-padded 2-character hexadecimal number, with ``0x`` prefix and uppercase (``X``) hex-letters.
68+
69+
.. _TEMPLATES/Variables:
70+
71+
Predefined Variables
72+
********************
73+
74+
.. grid:: 2
75+
76+
.. grid-item::
77+
:columns: 6
78+
79+
*pyVersioning* offers lots of predefined variables. A full list of variables and there actual values can be
80+
printed using the :code:`pyVersioning variables` command in the command line interface.
81+
82+
The following root-level variables are defined:
83+
84+
``version``
85+
Version information.
86+
``git``
87+
Information collected from version control system Git like branch name, tag name, commit date, commit hash, ...
88+
``project``
89+
Project information mainly provided by the :file:`.pyVersioning.yaml` configuration file.
90+
``build``
91+
Build information mainly provided by the :file:`.pyVersioning.yaml` configuration file.
92+
``tool``
93+
Tool information about pyVersioning.
94+
``platform``
95+
Platform information.
96+
97+
.. seealso::
98+
99+
:ref:`USAGE/variables`
100+
101+
.. grid-item::
102+
:columns: 6
103+
104+
.. card:: Variables
105+
106+
.. code-block:: text
107+
108+
$> pyVersioning.exe variables
109+
version : v0.0.0
110+
tool : pyVersioning 0.17.0
111+
name : pyVersioning
112+
version : 0.17.0
113+
project : - v0.0.0
114+
name :
115+
variant :
116+
version : v0.0.0
117+
build : <pyVersioning.Build object at 0x000001F3FF7F46C0>
118+
date : 2025-04-21
119+
time : 10:43:02.882194
120+
compiler : <pyVersioning.Compiler object at 0x000001F3819B63E0>
121+
name :
122+
version : v0.0.0
123+
configuration :
124+
options :
125+
git : <pyVersioning.Git object at 0x000001F3819F5260>
126+
commit : <pyVersioning.Commit object at 0x000001F3819DA920>
127+
hash : 4f5b03b202887cab53ad27d80b0ed5bde028d705
128+
date : 2025-04-21
129+
time : 07:50:48
130+
author : Patrick Lehmann <Paebbels@gmail.com>
131+
name : Patrick Lehmann
132+
email : Paebbels@gmail.com
133+
committer : Patrick Lehmann <Paebbels@gmail.com>
134+
name : Patrick Lehmann
135+
email : Paebbels@gmail.com
136+
comment : Fixed binary output check.
137+
138+
oneline : Fixed binary output check.
139+
reference : dev
140+
tag :
141+
branch : dev
142+
repository : git@github.com:Paebbels/pyVersioning.git
143+
platform : <pyVersioning.Platform object at 0x000001F3FF441510>
144+
ci_service : NO-CI
145+
env : Environment(..........................)
146+
147+
148+
149+
.. _TEMPLATES/ConfigurationFile:
150+
151+
Configuration File Variables
152+
============================
153+
154+
*pyVersioning* reads a :file:`.pyVersioning.yaml` file for static (per project) settings. These are also exposed as
155+
variables.
156+
157+
158+
159+
.. _TEMPLATES/Environment:
160+
161+
Environment Variables
162+
=====================
163+
164+
.. todo:: List environment variables.
165+
166+
167+
.. _TEMPLATES/Git:
168+
169+
Git Variables
170+
=============
171+
172+
.. _TEMPLATES/Git/Local:
173+
174+
Local Workstation
175+
-----------------
176+
177+
.. todo:: List Git variables.
178+
179+
180+
181+
.. _TEMPLATES/Git/AppVeyor:
182+
183+
AppVayor
184+
--------
185+
186+
.. todo:: List AppVayor variables.
187+
188+
189+
190+
.. _TEMPLATES/Git/GitHub:
191+
192+
GitHub
193+
------
194+
195+
.. todo:: List GitHub variables.
196+
197+
198+
199+
.. _TEMPLATES/Git/GitLab:
200+
201+
GitLab
202+
------
203+
204+
.. todo:: List GitLab variables.
205+
206+
207+
208+
.. _TEMPLATES/Git/TravisCI:
209+
210+
Travis-CI
211+
---------
212+
213+
.. todo:: List Travis-CI variables.
5214

0 commit comments

Comments
 (0)