Skip to content

Commit efdbdcd

Browse files
PaebbelsPaebbels
committed
doc: Updated build.sh for Ruff! 3.0b1.
1 parent 9cfdf1b commit efdbdcd

File tree

4 files changed

+84
-61
lines changed

4 files changed

+84
-61
lines changed

‎OsvvmScriptsCore.tcl‎

Lines changed: 22 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -92,8 +92,9 @@ proc StartUp {} {
9292

9393

9494
namespace eval ::osvvm {
95-
96-
95+
variable _ruff_preamble {
96+
Here could be some documentation for the namespace.
97+
}
9798

9899
# -------------------------------------------------
99100
# IterateFile
@@ -1089,25 +1090,27 @@ proc LinkCurrentLibraries {} {
10891090
#
10901091
proc analyze {FileName args} {
10911092
# Analyze an HDL source file.
1092-
#
1093+
#
10931094
# FileName - Path to the HDL source file.
10941095
# args - Further options.
1095-
#
1096-
# This procedure executes a tool-specific analyze command depending on what tool was detected. Some of the used
1097-
# analyze option depend on the current context. For example the use VHDL library this source file and its design units
1098-
# are compiled into, depend on the last [library] call.
1099-
#
1100-
# **Procedures influencing the context for the `analyze` command:**
1101-
#
1102-
# * [library] - set the VHDl working library
1103-
# * [SetVHDLVersion] - tbd
1104-
# * [SetExtendedAnalyzeOptions] - tbd
1105-
# * [SetVhdlAnalyzeOptions] - tbd
1106-
#
1096+
#
1097+
# This procedure executes a tool-specific analyze command depending on what tool was detected. Some of the used
1098+
# analyze option depend on the current context. For example the use VHDL library this source file and its design units
1099+
# are compiled into, depend on the last [library] call.
1100+
#
1101+
# **Procedures influencing the context for the `analyze` command:**
1102+
#
1103+
# * [library] - set the VHDL working library
1104+
# * [SetVHDLVersion] - tbd
1105+
# * [SetExtendedAnalyzeOptions] - tbd
1106+
# * [SetVhdlAnalyzeOptions] - tbd
1107+
#
11071108
# **Supported HDL sourcefile languages:**
1108-
# * VHDL `*.vhd`/`*.vhdl`
1109-
# * Verilog `*.v`
1110-
# * SystemVerilog `*.sv`
1109+
# * VHDL `*.vhd`/`*.vhdl`
1110+
# * Verilog `*.v`
1111+
# * SystemVerilog `*.sv`
1112+
#
1113+
# :ref:`ghdl::analyze <RUFF/osvvm/ghdl/analyze>`
11111114
variable AnalyzeErrorCount
11121115
variable AnalyzeErrorStopCount
11131116
variable ConsecutiveAnalyzeErrors
@@ -1473,7 +1476,7 @@ proc RunTest {FileName {SimName ""} args} {
14731476
puts "RunTest $RunArgs" ; # EchoOsvvmCmd
14741477
set CompoundCommand TRUE
14751478

1476-
if {$SimName eq ""} {
1479+
if {$SimName eq ""} {
14771480
set SimName [file rootname [file tail $FileName]]
14781481
TestName $SimName
14791482
} else {

‎doc/Glossary.rst‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,10 @@ Glossary
66
OSVVM
77
tbd
88

9-
TCL
10-
tbd
9+
Tcl
10+
Tool Command Language
11+
12+
.. rubric:: Further reading
13+
14+
* https://en.wikipedia.org/wiki/Tcl
15+
* https://www.tcl-lang.org/

‎doc/build.sh‎

Lines changed: 52 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ DEBUG=0
5050
COMMAND=1
5151
CLEAN=0
5252
RUFF=0
53+
POST=1
5354
SPHINX=0
5455
BUILDERS=()
5556
HTML=0
@@ -68,15 +69,18 @@ while [[ $# -gt 0 ]]; do
6869
COMMAND=3
6970
RUFF=1
7071
;;
72+
-n|--no-post-process)
73+
POST=0
74+
;;
7175
-s|--sphinx)
7276
COMMAND=3
7377
SPHINX=1
7478
;;
75-
--html)
79+
-H|--html)
7680
HTML=1
7781
BUILDERS+=("html")
7882
;;
79-
--latex)
83+
-l|--latex)
8084
LATEX=1
8185
BUILDERS+=("latex")
8286
;;
@@ -114,23 +118,24 @@ if [[ ${COMMAND} -le 1 ]]; then
114118
printf "%s\n" " ${ANSI_LIGHT_CYAN}$(basename "$0")${ANSI_NOCOLOR} [<verbosity>] [--clean] [--all] [--ruff] [--sphinx]"
115119
printf "\n"
116120
printf "%s\n" "${ANSI_CYAN}Common commands:${ANSI_NOCOLOR}"
117-
printf "%s\n" " -h --help Print this help page"
118-
printf "%s\n" " -c --clean Remove all generated files"
121+
printf "%s\n" " -h --help Print this help page"
122+
printf "%s\n" " -c --clean Remove all generated files"
119123
printf "\n"
120124
printf "%s\n" "${ANSI_CYAN}Steps:${ANSI_NOCOLOR}"
121-
printf "%s\n" " -a --all Run all steps (--ruff --sphinx)."
122-
printf "%s\n" " -r --ruff Extract code documentation from TCL code using Ruff!."
123-
printf "%s\n" " -s --sphinx Build documentation using Sphinx."
124-
printf "%s\n" " If not specified, build only HTML variant."
125-
printf "%s\n" " --html Build HTML documentation using Sphinx."
126-
printf "%s\n" " --latex Build LaTeX documentation using Sphinx."
125+
printf "%s\n" " -a --all Run all steps (--ruff --sphinx)."
126+
printf "%s\n" " -r --ruff Extract code documentation from TCL code using Ruff!."
127+
printf "%s\n" " -n --no-post-process No post-processing of Ruff! generated files."
128+
printf "%s\n" " -s --sphinx Build documentation using Sphinx."
129+
printf "%s\n" " If not specified, build only HTML variant."
130+
printf "%s\n" " -H --html Build HTML documentation using Sphinx."
131+
printf "%s\n" " -l --latex Build LaTeX documentation using Sphinx."
127132
printf "\n"
128133
printf "%s\n" "${ANSI_CYAN}Verbosity:${ANSI_NOCOLOR}"
129-
printf "%s\n" " -v --verbose Print verbose messages."
130-
printf "%s\n" " -d --debug Print debug messages."
134+
printf "%s\n" " -v --verbose Print verbose messages."
135+
printf "%s\n" " -d --debug Print debug messages."
131136
printf "\n"
132137
printf "%s\n" "${ANSI_CYAN}Requirements:${ANSI_NOCOLOR}"
133-
printf "%s\n" " -i --install Install / update required Python packages."
138+
printf "%s\n" " -i --install Install / update required Python packages."
134139
exit ${COMMAND}
135140
fi
136141

@@ -206,30 +211,40 @@ EOF
206211
ls ${RUFF_DIR} | sed 's/^/ /'
207212
fi
208213

209-
printf -- "${ANSI_MAGENTA}[BUILD] Patch ReST files ...\n"
210-
#printf -- " ${ANSI_CYAN}Patching ${RUFF_DIR}/index.rst ...${ANSI_NOCOLOR}\n"
211-
#sed -i -E 's/.rst$//g' ${RUFF_DIR}/index.rst # for page split
212-
#sed -i -E 's/:maxdepth: .*$/:hidden:/g' ${RUFF_DIR}/index.rst # for page split
213-
#sed -i -E 's/:caption: .*$//g' ${RUFF_DIR}/index.rst # for page split
214-
#sed -i -E 's/ osvvm$//g' ${RUFF_DIR}/index.rst # for page split
215-
216-
for rstFile in ${RUFF_DIR}/*.rst; do
217-
printf -- " ${ANSI_CYAN}Patching ${rstFile} ...${ANSI_NOCOLOR}\n"
218-
test $VERBOSE -eq 1 && printf -- " ${ANSI_LIGHT_CYAN}Remove intermediate 'Commands' heading${ANSI_NOCOLOR}\n"
219-
sed -i -E 's/^Commands//g' ${rstFile}
220-
sed -i -E 's/^========//g' ${rstFile}
221-
222-
test $VERBOSE -eq 1 && printf -- " ${ANSI_LIGHT_CYAN}Correct index entry${ANSI_NOCOLOR}\n"
223-
sed -i -E 's/ single: ::osvvm::/ single: ::osvvm; /g' ${rstFile}
224-
225-
test $VERBOSE -eq 1 && printf -- " ${ANSI_LIGHT_CYAN}Remove links from headings${ANSI_NOCOLOR}\n"
226-
sed -i -E 's/^``(\w+)``.*$/\1/g' ${rstFile}
227-
#sed -i -E 's/-----------------------------------------------$//g' ${rstFile} # for pagesplit
228-
sed -i -E 's/-----------------------------------------$//g' ${rstFile} # for single page
229-
230-
test $VERBOSE -eq 1 && printf -- " ${ANSI_LIGHT_CYAN}Remove inline code markers from parameter names${ANSI_NOCOLOR}\n"
231-
sed -i -E 's/^:``(\w+)``:/:\1:/g' ${rstFile}
232-
done
214+
if [[ ${POST} -eq 1 ]]; then
215+
printf -- "${ANSI_MAGENTA}[BUILD] Patch ReST files ...${ANSI_NOCOLOR}\n"
216+
#printf -- " ${ANSI_CYAN}Patching ${RUFF_DIR}/index.rst ...${ANSI_NOCOLOR}\n"
217+
#sed -i -E 's/.rst$//g' ${RUFF_DIR}/index.rst # for page split
218+
#sed -i -E 's/:maxdepth: .*$/:hidden:/g' ${RUFF_DIR}/index.rst # for page split
219+
#sed -i -E 's/:caption: .*$//g' ${RUFF_DIR}/index.rst # for page split
220+
#sed -i -E 's/ osvvm$//g' ${RUFF_DIR}/index.rst # for page split
221+
222+
for rstFile in ${RUFF_DIR}/*.rst; do
223+
printf -- " ${ANSI_CYAN}Patching ${rstFile} ...${ANSI_NOCOLOR}\n"
224+
225+
filename="${rstFile##*/}"
226+
namespace="${filename%.*}"
227+
228+
test $VERBOSE -eq 1 && printf -- " ${ANSI_LIGHT_CYAN}Insert index entry for '${namespace}' namespace${ANSI_NOCOLOR}\n"
229+
sed -i -E "/^\.\. _r-${namespace}:$/a \\\n.. index::\n single: ${namespace}" "${rstFile}"
230+
231+
test $VERBOSE -eq 1 && printf -- " ${ANSI_LIGHT_CYAN}Remove intermediate 'Commands' heading${ANSI_NOCOLOR}\n"
232+
sed -i -E "/^\.\. _r-3a3a${namespace}.*Commands:/,/^========$/d" "${rstFile}"
233+
234+
test $VERBOSE -eq 1 && printf -- " ${ANSI_LIGHT_CYAN}Correct index entry${ANSI_NOCOLOR}\n"
235+
sed -i -E "/^\.\. index::/{N; N; s|\n\.\. index::||}" "${rstFile}"
236+
sed -i -E "s| single: ${namespace} namespace;| single: ${namespace}; |g" "${rstFile}"
237+
238+
test $VERBOSE -eq 1 && printf -- " ${ANSI_LIGHT_CYAN}Remove backticks from heading${ANSI_NOCOLOR}\n"
239+
sed -i -E 's/^``(\w+)``$/\1/g' "${rstFile}"
240+
sed -i -E 's/----$//g' "${rstFile}"
241+
242+
test $VERBOSE -eq 1 && printf -- " ${ANSI_LIGHT_CYAN}Remove inline code markers from parameter names${ANSI_NOCOLOR}\n"
243+
sed -i -E 's/^:``(\w+)``:/:\1:/g' "${rstFile}"
244+
done
245+
else
246+
printf -- "${ANSI_MAGENTA}[BUILD] Patch ReST files ... ${ANSI_YELLOW}[SKIPPED]\n${ANSI_NOCOLOR}"
247+
fi
233248
fi
234249

235250
# Build documentation using Sphinx

‎doc/index.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -31,12 +31,12 @@ License
3131

3232
.. only:: html
3333

34-
The ``::osvvm`` TCL namespace (source code) is licensed under `Apache License 2.0 <Code-License.html>`__. |br|
34+
The ``::osvvm`` Tcl namespace (source code) is licensed under `Apache License 2.0 <Code-License.html>`__. |br|
3535
The accompanying documentation is licensed under `Creative Commons - Attribution 4.0 (CC-BY 4.0) <Doc-License.html>`__.
3636

3737
.. only:: latex
3838

39-
This ``::osvvm`` TCL namespace (source code) is licensed under **Apache License 2.0**. |br|
39+
This ``::osvvm`` Tcl namespace (source code) is licensed under **Apache License 2.0**. |br|
4040
The accompanying documentation is licensed under **Creative Commons - Attribution 4.0 (CC-BY 4.0)**.
4141

4242

@@ -66,7 +66,7 @@ License
6666
:caption: References and Reports
6767
:hidden:
6868

69-
TCL Command Reference <osvvm-scripts/osvvm>
69+
Tcl Command Reference <osvvm-scripts/osvvm>
7070
YAML/index
7171

7272
.. raw:: latex

0 commit comments

Comments
 (0)