Commit 6afafa1f authored by Adrian DC's avatar Adrian DC
Browse files

docs(mkdocs): implement 'mkdocs-exporter' and customize PDF style 

Signed-off-by: default avatarAdrian DC <radian.dc@gmail.com>
parent c14a469c

.gitignore

+1 −0
Changes for .gitignore: 1 added line, 0 removed lines.
Original line number Diff line number Diff line
@@ -17,6 +17,7 @@ dist/ 
/docs/.serve.pid

/docs/about

/docs/index.md

/docs/stylesheets/variables.scss

/public



# SonarQube files

.gitlab-ci.yml

+1 −0
Changes for .gitlab-ci.yml: 1 added line, 0 removed lines.
Original line number Diff line number Diff line
@@ -169,6 +169,7 @@ serve: 
    # Install dependencies

    - grep '^mkdocs[>=]\{1,\}.*\|^playwright' ./requirements/pages.txt | xargs -n1 -r pipx install

    - grep '^mkdocs-.*' ./requirements/pages.txt | xargs -r pipx inject mkdocs

    - grep '^git+.*mkdocs-exporter' ./requirements/pages.txt | xargs -r pipx inject mkdocs

    - playwright install chromium

  script:

    # Prepare documentation

README.md

+1 −0
Changes for README.md: 1 added line, 0 removed lines.
Original line number Diff line number Diff line
@@ -237,6 +237,7 @@ an environment variable `NO_COLOR=1` can be defined to disable colors. 
- [gitlab-release](https://pypi.org/project/gitlab-release/): Utility for publishing on GitLab

- [gcil](https://radiandevcore.gitlab.io/tools/gcil): Launch .gitlab-ci.yml jobs locally

- [mkdocs](https://www.mkdocs.org/): Project documentation with Markdown

- [mkdocs-exporter](https://adrienbrignon.github.io/mkdocs-exporter/): Exporter plugin for mkdocs documentation

- [mkdocs-material](https://squidfunk.github.io/mkdocs-material/): Material theme for mkdocs documentation

- [mypy](https://pypi.org/project/mypy/): Optional static typing for Python

- [pre-commit](https://pre-commit.com/): A framework for managing and maintaining pre-commit hooks

docs/.pages

+1 −0
Changes for docs/.pages: 1 added line, 0 removed lines.
Original line number Diff line number Diff line
@@ -4,5 +4,6 @@ nav: 
      - gitlab-projects-settings - Usage: index.md

  - About:

      - ‣ Changelog: about/changelog/

      - ‣ Documentation: documentation.pdf

      - ‣ License: about/license/

      - ‣ Quality: about/quality/

docs/prepare.sh

+40 −8
Changes for docs/prepare.sh: 40 added lines, 8 removed lines.
Original line number Diff line number Diff line
@@ -13,12 +13,36 @@ root_path="${docs_path%/*}" 
# Prepare cache

rm -f "${docs_path}/index.md"

rm -rf "${docs_path}/about"

rm -f "${docs_path}/stylesheets/variables.scss"



# Cleanup mode

if [ "${mode:-}" = '--clean' ]; then

  return 0

fi



# Configurations

projectAuthor=$(grep '^site_author: ' "${root_path}/mkdocs.yml" | cut -d':' -f2- | xargs echo)

projectCopyright=$(grep '^copyright: ' "${root_path}/mkdocs.yml" | cut -d':' -f2- | xargs echo)

projectDate=$(date '+%d/%m/%Y')

projectKey=$(grep '^sonar\.projectKey=' "${root_path}/sonar-project.properties" | cut -d'=' -f2)

projectName=$(grep '^PROJECT_NAME = ' "${root_path}/setup.py" | cut -d"'" -f2)

projectNamespace=$(grep '^PROJECT_NAMESPACE = ' "${root_path}/setup.py" | cut -d"'" -f2)

projectPackage=$(grep '^PROJECT_PACKAGE = ' "${root_path}/setup.py" | cut -d"'" -f2)

projectPages=$(grep '^site_url: ' "${root_path}/mkdocs.yml" | cut -d':' -f2- | xargs echo)

projectUrl=$(grep '^repo_url:' "${root_path}/mkdocs.yml" | cut -d':' -f2- | xargs echo)

projectVersion=$(git describe --abbrev=7 --always --long --tags)

projectYear=$(date '+%Y')



# Generate SCSS variables

{

  echo "\$projectAuthor: '${projectAuthor}';"

  echo "\$projectCopyright: '${projectCopyright}';"

  echo "\$projectDate: '${projectDate}';"

  echo "\$projectName: '${projectName}';"

  echo "\$projectVersion: '${projectVersion}';"

  echo "\$projectYear: '${projectYear}';"

} >"${docs_path}/stylesheets/variables.scss"



# Export usage

cp -f "${root_path}/README.md" "${docs_path}/index.md"

sed -i "s#\(\[.*\]\)(.*/docs/#\1(#g" "${docs_path}/index.md"
@@ -36,12 +60,22 @@ mkdir -p "${docs_path}/about/" 
if ! type git-cliff >/dev/null 2>&1; then

  alias git-cliff='./.tmp/git-cliff'

fi

git-cliff --no-exec --config "${root_path}/config/cliff.toml" --output "${docs_path}/about/changelog.md"

sed -i '/^- /{ s/</\&lt;/g; s/>/\&gt;/g; }' "${docs_path}/about/changelog.md"

{

  echo '---'

  echo 'pdf: false'

  echo '---'

  echo ''

  git-cliff --no-exec --config "${root_path}/config/cliff.toml" \

    | sed '/^- /{ s/</\&lt;/g; s/>/\&gt;/g; }'

} >"${docs_path}/about/changelog.md"

diff -u "${root_path}/CHANGELOG.md" "${docs_path}/about/changelog.md" || true



# Export about/license

{

  echo '---'

  echo 'pdf: false'

  echo '---'

  echo ''

  echo '# License'

  echo ''

  echo '---'
@@ -51,12 +85,10 @@ diff -u "${root_path}/CHANGELOG.md" "${docs_path}/about/changelog.md" || true 


# Generate about/quality

{

  projectKey=$(grep '^sonar\.projectKey=' "${root_path}/sonar-project.properties" | cut -d'=' -f2)

  projectName=$(grep '^PROJECT_NAME = ' "${root_path}/setup.py" | cut -d"'" -f2)

  projectNamespace=$(grep '^PROJECT_NAMESPACE = ' "${root_path}/setup.py" | cut -d"'" -f2)

  projectPackage=$(grep '^PROJECT_PACKAGE = ' "${root_path}/setup.py" | cut -d"'" -f2)

  projectPages=$(grep '^site_url: ' "${root_path}/mkdocs.yml" | cut -d':' -f2- | xargs echo)

  projectUrl=$(grep '^repo_url:' "${root_path}/mkdocs.yml" | cut -d':' -f2- | xargs echo)

  echo '---'

  echo 'pdf: false'

  echo '---'

  echo ''

  echo '# Quality'

  echo ''

  echo '---'