diff --git a/components/lazcontrols/docs/lazcontrols-project.xml b/components/lazcontrols/docs/lazcontrols-project.xml new file mode 100644 index 0000000000..bf495005c0 --- /dev/null +++ b/components/lazcontrols/docs/lazcontrols-project.xml @@ -0,0 +1,73 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/components/lazcontrols/docs/lazcontrols.css b/components/lazcontrols/docs/lazcontrols.css new file mode 100644 index 0000000000..8f131246a2 --- /dev/null +++ b/components/lazcontrols/docs/lazcontrols.css @@ -0,0 +1,205 @@ +/* + fpdoc.css modified for LazControls documentation + Default font size is 11pt + Font family fallbacks + Removed border, added vertical margins on DL + Added color and font weight for FILE + Added styling for footer separator and columns +*/ + +body { + background: white; + color: Black; + font-size: 11pt; + /* font-family: "Helvetica", "Arial", sans-serif; */ + font-family: "San Francisco", "Roboto", "Segoe UI", "Helvetica", "Arial", sans-serif; +} + +p, th, td, caption, h1, h2, h3, ul, ol, dl { + /* font-family: "Helvetica", "Arial", sans-serif; */ + font-family: "San Francisco", "Roboto", "Segoe UI", "Helvetica", "Arial", sans-serif; + color: black; +} + +tt, span.kw, pre { + /* font-family: "Courier New", Courier, monospace; */ + font-family: "Menlo", "Roboto Mono", "JetBrains Mono", "Courier New", Courier, monospace; + font-size: 1em; +} + +p, th, td, caption, ul, ol, dl, tt, span.kw, pre { + font-size: 1em; +} + +A:link { + color: blue; +} + +A:visited { + color: darkblue; +} + +A:active { + color: red; +} + +A { + text-decoration: none; +} + +A:hover { + text-decoration: underline; +} + +h1, h2, td.h2 { + color: #005A9C; +} + +/* Especially for Netscape on Linux: */ +h3, td.h3 { + font-size: 1em; +} + +/* source fragments */ +span.code { + white-space: nowrap; +} + +/* symbols in source fragments */ +span.sym { + color: darkred; +} + +/* keywords in source fragments */ +span.kw { + font-weight: bold; +} + +/* comments in source fragments */ +span.cmt { + color: darkcyan; + font-style: italic; +} + +/* directives in source fragments */ +span.dir { + color: darkyellow; + font-style: italic; +} + +/* numbers in source fragments */ +span.num { + color: darkmagenta; +} + +/* characters (#...) in source fragments */ +span.chr { + color: darkcyan; +} + +/* strings in source fragments */ +span.str { + color: blue; +} + +/* assembler passages in source fragments */ +span.asm { + color: green; +} + +td { + vertical-align: baseline; +} + +td.pre { + white-space: pre; +} + +table caption { + font-weight: bold; +} + +p.cmt { + color: gray; +} + +span.warning { + color: red; + font-weight: bold; +} + +/* !!!: How should we define this...? */ +span.file { + color: darkgreen; + font-weight: bold; + +} + +table.remark { + background-color: #ffffc0; +} + +table.bar { + background-color: #a0c0ff; +} + +table.footer { + margin-top: .5em; + width: 100%; + font-size: .875em; + /* font-style: italic; */ + font-style: normal; +} + +span.bartitle { + font-weight: bold; + font-style: italic; + color: darkblue; +} + +span.footer { + font-style: italic; + color: darkblue; +} + +/* definition list */ +dl { + /* border: 2px solid #ccc; */ + display: block; + margin: 1em 0 1em 0; +} + +/* definition list: term */ +dt { + /* + float: left; + clear: left; + */ + width: auto; /* normally browsers default width of largest item */ + /* padding-right: 1.25em; */ + font-weight: bold; + color: darkgreen; +} + +/* definition list: description */ +dd { + margin: 0 0 0 2em; + padding: 0 0 0.5em 0; +} + +/* for browsers in standards compliance mode */ +td p { + margin: 0; +} + +var { + font-weight: bold; +} + +hr.footer-sep { + margin-top: .667em; +} + +td.footer-doc { width: 40%; text-align: left; color: Black; } +td.footer-ver { width: 30%; text-align: center; color: Gray; } +td.footer-date { width: 30%; text-align: right; color: Gray; } diff --git a/components/lazcontrols/docs/make-docs.bat b/components/lazcontrols/docs/make-docs.bat new file mode 100644 index 0000000000..f69d104f84 --- /dev/null +++ b/components/lazcontrols/docs/make-docs.bat @@ -0,0 +1,82 @@ +@echo off + +REM ======================================================================= +REM Builds CHM and HTML help files for the LazControls package using the fpdoc utility. +REM Requires chm and xct files for rtl, fcl, lcl, and lazutils in the Lazarus docs\chm directory. +REM fpdoc will fail if they are not present. +REM Requires git command line client to get the commit hash for the repository. +REM ======================================================================= + +REM ====================================== +REM SET THE CORRECT PATHS FOR YOUR SYSTEM +REM ====================================== + +REM lazarus documentation directory +set docdir=..\..\..\docs +REM fpdoc executable directory +set fpcdir=..\..\..\..\lazarus-2.2.0-RC2\fpc\3.2.2\bin\x86_64-win64 +REM directory with lazarus git repository +set gitdir=..\..\..\..\usr\work\git-lazarus + +REM values used in the footer +set pkgtitle=Lazarus Controls Package (LazControls) + +REM CHANGE THIS BEFORE BUILDING +set version=2.3.0 + +REM commit SHA +git -C %gitdir% describe --all --long > describe.txt +for /f "delims=-g tokens=1-3" %%a in (describe.txt) do set commit=%%c +del describe.txt + +REM date stamp in YYYY-MM-DD format +for /f "usebackq tokens=2 delims== " %%i in (`wmic os get LocalDateTime /value`) do set token10=%%i +set dtstamp=%token10:~0,4%-%token10:~4,2%-%token10:~6,2% +set token10= +REM TODO: wmic is deprecated in Windows 11... check for powershell equivalent + +echo %pkgtitle% %version%-%commit% %dtstamp% + +REM generate footer with title, version, commit SHA, date stamp +REM footer is included using the fpdoc project file + +echo|(set /p="
" & echo.) > lazcontrols-footer.xml +echo|(set /p="" & echo.) >> lazcontrols-footer.xml +echo|(set /p=" " & echo.) >> lazcontrols-footer.xml +echo|(set /p=" " & echo.) >> lazcontrols-footer.xml +echo|(set /p=" " & echo.) >> lazcontrols-footer.xml +echo|(set /p=" " & echo.) >> lazcontrols-footer.xml +echo|(set /p=" " & echo.) >> lazcontrols-footer.xml +echo|(set /p="
%pkgtitle%Version %version%-%commit%Generated %dtstamp%
" & echo.) >> lazcontrols-footer.xml + +echo. +echo Generating CHM help... + +REM generate chm format +REM imports done manually to set the correct prefix for the output format +REM output to current directory + +%fpcdir%\fpdoc --project=lazcontrols-project.xml --format=chm --verbose --import="%docdir%\chm\rtl.xct,ms-its:rtl.chm::/" --import="%docdir%\chm\fcl.xct,ms-its:fcl.chm::/" --import="%docdir%\chm\lcl.xct,ms-its:lcl.chm::/" --import="%docdir%\chm\lazutils.xct,ms-its:lazutils.chm::/" > .\build_chm.log + +echo. +echo Generating HTML help... + +REM generate html format +REM imports done manually to set the correct prefix for the output format +REM html written to lazcontrols sub-directory + +%fpcdir%\fpdoc --project=lazcontrols-project.xml --format=html --verbose --import="%docdir%\chm\rtl.xct,..\rtl\" --import="%docdir%\chm\fcl.xct,..\fcl\" --import="%docdir%\chm\lcl.xct,..\lcl\" --import="%docdir%\chm\lazutils.xct,..\lazutils\" --output=lazcontrols > .\build_html.log + +REM create an archive file with html content +REM echo Creating archive: docs-html-lazcontrols-%dtstamp%.7z +REM 7z a -t7z -mx9 -r docs-html-lazcontrols-%dtstamp%.7z .\lazcontrols\ > NUL + +REM move generated html to lazarus docs\html directory +REM move /Y .\lazcontrols %docdir%\html\ + +REM move generated chm, xct to lazarus docs directory +REM move /Y lazcontrols.chm %docdir%\chm\ +REM move /Y lazcontrols.xct %docdir%\chm\ + +REM discard generated footer file +del lazcontrols-footer.xml diff --git a/components/lazcontrols/docs/make-docs.sh b/components/lazcontrols/docs/make-docs.sh new file mode 100644 index 0000000000..086d7b4b07 --- /dev/null +++ b/components/lazcontrols/docs/make-docs.sh @@ -0,0 +1,71 @@ +#!/bin/bash +#====================================================================== +# Builds CHM and HTML help files for the LazControls package using the fpdoc utility. +# Requires chm and xct files for rtl, fcl, lcl, and lazutils in the Lazarus docs/chm directory. +# fpdoc will fail if they are not present. +# Requires git command line client to get the commit hash for the repository. +#====================================================================== + +#======================================= +# SET THE CORRECT PATHS FOR YOUR SYSTEM +#======================================= +# lazarus documentation directory +docdir="../../../docs" +# fpdoc executable directory +fpcdir="../../../../lazarus-2.2.0-RC2/fpc/3.2.2/bin/x86_64-win64" +# directory with lazarus git repository +gitdir="../../../../usr/work/git-lazarus" + +# values used in the footer +pkgtitle="Lazarus Controls Package (LazControls)" +# CHANGE THIS BEFORE BUILDING +version="2.3.0" +# commit SHA +commit=`git -C "$gitdir" describe --all --long | cut -d "-" -f 3 | cut -b "2-"` +# date stamp in YYYY-MM-DD format +dtstamp=`date +"%Y-%m-%d"` + +echo -e "\n\e[7m $pkgtitle $version—$commit $dtstamp \e[0m"; + +# generate footer with title, version, commit SHA, date stamp +# footer is included using the fpdoc project file +cat << EOT > lazcontrols-footer.xml +
+ + + + + + +
$pkgtitleVersion $version-$commitGenerated $dtstamp
+EOT + +echo "" +echo "Generating CHM help..." + +# generate chm format +# imports done manually to set the correct prefix for the output format +# output to current directory +$fpcdir/fpdoc --project=lazcontrols-project.xml --format=chm --verbose --import="$docdir/chm/rtl.xct,ms-its:rtl.chm::/" --import="$docdir/chm/fcl.xct,ms-its:fcl.chm::/" --import="$docdir/chm/lcl.xct,ms-its:lcl.chm::/" --import="$docdir/chm/lazutils.xct,ms-its:lazutils.chm::/" 2>&1 | tee ./build_chm.log + +echo "" +echo "Generating HTML help..." + +# generate html format +# imports done manually to set the correct prefix for the output format +# html written to lazcontrols sub-directory +$fpcdir/fpdoc --project=lazcontrols-project.xml --format=html --verbose --import="$docdir/chm/rtl.xct,../rtl/" --import="$docdir/chm/fcl.xct,../fcl/" --import="$docdir/chm/lcl.xct,../lcl/" --import="$docdir/chm/lazutils.xct,../lazutils/" --output=lazcontrols 2>&1 | tee ./build_html.log + +# create an archive file with html content +#echo "Creating archive: docs-html-lazcontrols-$dtstamp.7z" +#7z a -t7z -mx9 -r docs-html-lazcontrols-$dtstamp.7z ./lazcontrols/ > /dev/null + +# move generated html to lazarus docs/html directory +#rm -vrf $docdir/html/lazcontrols/ +#mv -vrf ./lazcontrols $docdir/html/ + +# move generated chm, xct to lazarus docs directory +#mv -v lazcontrols.{chm,xct} $docdir/chm/ + +# discard generated footer file +rm lazcontrols-footer.xml