zensical.toml

[project]
site_name = "DHCW Software Engineering Handbook"
site_description = "GIG Cymru NHS Wales - DHCW Software Engnineering Handbook provides guidance on software development standards, practices, and tools to ensure high-quality software delivery."
site_url = "https://gigcymru.github.io/dhcw-software-engineering-handbook/"
repo_url = "https://github.com/GIGCymru/dhcw-software-engineering-handbook/"
docs_dir = "doc"
edit_uri = "edit/main/doc/"
copyright = "Copyright &copy; 2025 GIG Cymru - NHS Wales – <a href=\"#__consent\">Change cookie settings</a>"
extra_css = ["stylesheets/extra.css"]

# Navigation structure
nav = [
  {"Home" = "index.md"},
  {"Software Development Handbook" = [
    {"Introduction" = "software-development-handbook/introduction.md"},
    {"Development tools" = "software-development-handbook/development-tools.md"},
    {"Development principles" = "software-development-handbook/development-principles.md"},
    {"Agile delivery using Scrum" = "software-development-handbook/agile-delivery-using-scrum.md"},
    {"Testing" = "software-development-handbook/testing.md"},
    {"Security" = "software-development-handbook/security.md"},
    {"User interface and accessibility standards" = "software-development-handbook/user-interface-and-accessibility-standards.md"},
    {"Documentation" = "software-development-handbook/documentation.md"},
    {"Exceptions" = "software-development-handbook/exceptions.md"},
    {"Essential good practice checklists" = "software-development-handbook/essential-good-practice-checklists.md"},
  ]},
  {"Using Source Control" = [
    {"Introduction" = "using-source-control/introduction.md"},
    {"Use our source control systems" = "using-source-control/use-our-source-control-systems.md"},
    {"What to include in source control" = "using-source-control/what-to-include-in-source-control.md"},
    {"Use Git" = "using-source-control/use-git.md"},
    {"Establish a clear repo structure" = "using-source-control/establish-a-clear-repo-structure.md"},
    {"Commit changes early and often" = "using-source-control/commit-changes-early-and-often.md"},
    {"Write clear commit messages" = "using-source-control/write-clear-commit-messages.md"},
    {"Review your code" = "using-source-control/review-your-code.md"},
    {"Squash commits before merging" = "using-source-control/squash-commits-before-merging.md"},
    {"Follow a branching strategy" = "using-source-control/follow-a-branching-strategy.md"},
    {"Adopt trunk based development and continuous integration" = "using-source-control/adopt-trunk-based-development-and-continuous-integration.md"},
    {"Implement a versioning strategy" = "using-source-control/implement-a-versioning-strategy.md"},
    {"Keep your repo organised" = "using-source-control/keep-your-repo-organised.md"},
    {"Always deploy from source control" = "using-source-control/always-deploy-from-source-control.md"},
    {"Select and configure Git clients" = "using-source-control/select-and-configure-git-clients.md"},
    {"Exceptions" = "using-source-control/exceptions.md"},
    {"Essential good practice checklist" = "using-source-control/essential-good-practice-checklist.md"},
  ]},
  {"Organising Your Solution" = [
    {"Introduction" = "organising-your-solution/introduction.md"},
    {"Organise your solution to accord with our conventions" = "organising-your-solution/organise-your-solution-to-accord-with-our-conventions.md"},
    {"Use physical folders" = "organising-your-solution/use-physical-folders.md"},
    {"Create a root folder for your solution" = "organising-your-solution/create-a-root-folder-for-your-solution.md"},
    {"Provide a readme file" = "organising-your-solution/provide-a-readme-file.md"},
    {"Create a editorconfig file" = "organising-your-solution/create-a-editorconfig-file.md"},
    {"Create a source folder" = "organising-your-solution/create-a-source-folder.md"},
    {"Use additional sub folders for dependency layers" = "organising-your-solution/use-additional-sub-folders-for-dependency-layers.md"},
    {"Use sub folders within visual studio projects" = "organising-your-solution/use-sub-folders-within-visual-studio-projects.md"},
    {"Use existing conventions for project types" = "organising-your-solution/use-existing-conventions-for-project-types.md"},
    {"Create a specification folder" = "organising-your-solution/create-a-specification-folder.md"},
    {"Provide a test folder" = "organising-your-solution/provide-a-test-folder.md"},
    {"Provide a documents folder" = "organising-your-solution/provide-a-documents-folder.md"},
    {"Provide a build folder" = "organising-your-solution/provide-a-build-folder.md"},
    {"Provide a scripts folder" = "organising-your-solution/provide-a-scripts-folder.md"},
    {"Provide a deploy folder" = "organising-your-solution/provide-a-deploy-folder.md"},
    {"Provide an examples folder" = "organising-your-solution/provide-an-examples-folder.md"},
    {"Exceptions prove the rule" = "organising-your-solution/exceptions-prove-the-rule.md"},
    {"Good practice checklists" = "organising-your-solution/good-practice-checklists.md"},
  ]},
  {"General Coding Standards" = [
    {"Introduction" = "general-coding-standards/introduction.md"},
    {"Write clean code" = "general-coding-standards/write-clean-code.md"},
    {"Follow SOLID principles" = "general-coding-standards/follow-solid-principles.md"},
    {"Follow Microsoft's coding conventions" = "general-coding-standards/follow-microsofts-coding-conventions.md"},
    {"Analyse your code" = "general-coding-standards/analyse-your-code.md"},
    {"Exceptions" = "general-coding-standards/exceptions.md"},
    {"Examples" = "general-coding-standards/examples.md"},
    {"Essential good practice checklist" = "general-coding-standards/essential-good-practice-checklist.md"},
  ]},
  {"T-SQL Coding Standard" = [
    {"Introduction" = "t-sql-coding-standard/introduction.md"},
    {"Avoid using t SQL to execute business logic" = "t-sql-coding-standard/avoid-using-t-sql-to-execute-business-logic.md"},
    {"Follow these rules when using an object relational mapper ORM" = "t-sql-coding-standard/follow-these-rules-when-using-an-object-relational-mapper-orm.md"},
    {"General good practice" = "t-sql-coding-standard/general-good-practice.md"},
    {"Follow out table design rules schemes and indexes" = "t-sql-coding-standard/follow-out-table-design-rules-schemes-and-indexes.md"},
    {"Follow our table rules columns and datatypes" = "t-sql-coding-standard/follow-our-table-rules-columns-and-datatypes.md"},
    {"Apply code analysis rules" = "t-sql-coding-standard/apply-code-analysis-rules.md"},
    {"Working with transactions" = "t-sql-coding-standard/working-with-transactions.md"},
    {"Top N and Order By" = "t-sql-coding-standard/top-n-and-order-by.md"},
    {"XML and JSON" = "t-sql-coding-standard/xml-and-json.md"},
    {"Date and time" = "t-sql-coding-standard/date-and-time.md"},
    {"Aliases" = "t-sql-coding-standard/aliases.md"},
    {"Views" = "t-sql-coding-standard/views.md"},
    {"Stored procedures" = "t-sql-coding-standard/stored-procedures.md"},
    {"Handling exceptions" = "t-sql-coding-standard/handling-exceptions.md"},
    {"Working with user defined functions UDF" = "t-sql-coding-standard/working-with-user-defined-functions-udf.md"},
    {"Working with triggers" = "t-sql-coding-standard/working-with-triggers.md"},
    {"Permissions" = "t-sql-coding-standard/permissions.md"},
    {"Working with SQL server agent" = "t-sql-coding-standard/working-with-sql-server-agent.md"},
    {"Follow our naming rules see also table design rules" = "t-sql-coding-standard/follow-our-naming-rules-see-also-table-design-rules.md"},
    {"Follow our code layout rules" = "t-sql-coding-standard/follow-our-code-layout-rules.md"},
    {"Code comments" = "t-sql-coding-standard/code-comments.md"},
    {"Exceptions prove the rule" = "t-sql-coding-standard/exceptions-prove-the-rule.md"},
    {"Examples" = "t-sql-coding-standard/examples.md"},
    {"SQL prompt configuration" = "t-sql-coding-standard/sql-prompt-configuration.md"},
    {"Good practice checklists" = "t-sql-coding-standard/good-practice-checklists.md"},
  ]},
  {"RESTful API Standards" = [
    {"Introduction" = "restful-api-standards/introduction.md"},
    {"General principles" = "restful-api-standards/general-principles.md"},
    {"Definitions" = "restful-api-standards/definitions.md"},
    {"FHIR Fast Healthcare Interoperability Standards" = "restful-api-standards/fhir-fast-healthcare-interoperability-standards.md"},
    {"Data classification" = "restful-api-standards/data-classification.md"},
    {"Open API specification" = "restful-api-standards/open-api-specification.md"},
    {"Url structure" = "restful-api-standards/url-structure.md"},
    {"Retrieving related data" = "restful-api-standards/retrieving-related-data.md"},
    {"HTTP implementation" = "restful-api-standards/http-implementation.md"},
    {"Payload rules" = "restful-api-standards/payload-rules.md"},
    {"JSON response payload structure" = "restful-api-standards/json-response-payload-structure.md"},
    {"Paging" = "restful-api-standards/paging.md"},
    {"Filtering" = "restful-api-standards/filtering.md"},
    {"Sorting" = "restful-api-standards/sorting.md"},
    {"Compound collection operations" = "restful-api-standards/compound-collection-operations.md"},
    {"Naming" = "restful-api-standards/naming.md"},
    {"Error reporting" = "restful-api-standards/error-reporting.md"},
    {"Performance and response times" = "restful-api-standards/performance-and-response-times.md"},
    {"Concurrency control" = "restful-api-standards/concurrency-control.md"},
    {"Handling transient faults" = "restful-api-standards/handling-transient-faults.md"},
    {"API gateway pattern" = "restful-api-standards/api-gateway-pattern.md"},
    {"OWASP top 10" = "restful-api-standards/owasp-top-10.md"},
    {"Secrets and certificate management" = "restful-api-standards/secrets-and-certificate-management.md"},
    {"Encryption" = "restful-api-standards/encryption.md"},
    {"Security headers" = "restful-api-standards/security-headers.md"},
    {"HTTP message caching" = "restful-api-standards/http-message-caching.md"},
    {"Authentication and authorisation" = "restful-api-standards/authentication-and-authorisation.md"},
    {"API management" = "restful-api-standards/api-management.md"},
    {"Testing" = "restful-api-standards/testing.md"},
    {"Tooling" = "restful-api-standards/tooling.md"},
    {"Documentation" = "restful-api-standards/documentation.md"},
    {"Appendix A classifications" = "restful-api-standards/appendix-a-classifications.md"},
    {"Essential good practice checklist" = "restful-api-standards/essential-good-practice-checklist.md"},
  ]},
  {"Azure DevOps Handbook" = [
    {"Introduction" = "azure-devops-handbook/introduction.md"},
    {"Azure DevOps basics" = "azure-devops-handbook/azure-devops-basics.md"},
    {"Joining an existing project" = "azure-devops-handbook/joining-an-existing-project.md"},
    {"Creating a new project" = "azure-devops-handbook/creating-a-new-project.md"},
    {"Adding users and Teams" = "azure-devops-handbook/adding-users-and-teams.md"},
    {"Planning and tracking work with Azure boards" = "azure-devops-handbook/planning-and-tracking-work-with-azure-boards.md"},
    {"Managing source code with Azure repos" = "azure-devops-handbook/managing-source-code-with-azure-repos.md"},
    {"Automating builds and deployments with Azure pipelines" = "azure-devops-handbook/automating-builds-and-deployments-with-azure-pipelines.md"},
    {"Configuring agents for Azure pipelines" = "azure-devops-handbook/configuring-agents-for-azure-pipelines.md"},
    {"Sharing code with Azure artifacts" = "azure-devops-handbook/sharing-code-with-azure-artifacts.md"},
    {"Defining and running test cases with Azure test plans" = "azure-devops-handbook/defining-and-running-test-cases-with-azure-test-plans.md"},
    {"Using wikis" = "azure-devops-handbook/using-wikis.md"},
    {"Creating and managing dashboards" = "azure-devops-handbook/creating-and-managing-dashboards.md"},
    {"Managing user settings" = "azure-devops-handbook/managing-user-settings.md"},
    {"Project housekeeping tasks" = "azure-devops-handbook/project-housekeeping-tasks.md"},
    {"Securing your projects" = "azure-devops-handbook/securing-your-projects.md"},
    {"Managing costs" = "azure-devops-handbook/managing-costs.md"},
    {"Support and troubleshooting" = "azure-devops-handbook/support-and-troubleshooting.md"},
    {"Enabling GitHub Advanced Security" = "azure-devops-handbook/enabling-github-advanced-security.md"},
    {"Connecting Defender for Cloud DevOps" = "azure-devops-handbook/connecting-defender-for-cloud-devops.md"},
    {"Using Azure DevOps extensions" = "azure-devops-handbook/using-azure-devops-extensions.md"},
    {"Data privacy and availability" = "azure-devops-handbook/data-privacy-and-availability.md"},
    {"Essential good practice checklist" = "azure-devops-handbook/essential-good-practice-checklist.md"},
  ]},
  {"Software Subscriptions" = [
    {"Introduction" = "software-subscriptions/introduction.md"},
    {"What subscriptions are available" = "software-subscriptions/what-subscriptions-are-available.md"},
    {"Identify the subscription you need" = "software-subscriptions/identify-the-subscription-you-need.md"},
    {"Requesting a subscription" = "software-subscriptions/requesting-a-subscription.md"},
    {"Cancelling a subscription" = "software-subscriptions/cancelling-a-subscription.md"},
    {"Managing subscriptions" = "software-subscriptions/managing-subscriptions.md"},
  ]},
  {"Test Summary Report" = [
    {"Introduction" = "test-summary-report/introduction.md"},
    {"When to create a test summary report" = "test-summary-report/when-to-create-a-test-summary-report.md"},
    {"Characteristics of a good test summary report" = "test-summary-report/characteristics-of-a-good-test-summary-report.md"},
    {"Cover page" = "test-summary-report/cover-page.md"},
    {"Table of contents" = "test-summary-report/table-of-contents.md"},
    {"Document location" = "test-summary-report/document-location.md"},
    {"Relevant documents" = "test-summary-report/relevant-documents.md"},
    {"Version control" = "test-summary-report/version-control.md"},
    {"Reviews and approvals" = "test-summary-report/reviews-and-approvals.md"},
    {"Summary of testing" = "test-summary-report/summary-of-testing.md"},
    {"Test metrics" = "test-summary-report/test-metrics.md"},
    {"Further metrics" = "test-summary-report/further-metrics.md"},
    {"Filename" = "test-summary-report/filename.md"},
    {"Layout and formatting" = "test-summary-report/layout-and-formatting.md"},
    {"Example reports" = "test-summary-report/example-reports.md"},
    {"Exceptions prove the rule" = "test-summary-report/exceptions-prove-the-rule.md"},
  ]},
  {"Testing for Lost Updates" = [
    {"Introduction" = "testing-lost-updates/introduction.md"},
    {"Whats a lost update" = "testing-lost-updates/whats-a-lost-update.md"},
    {"How do you test for lost updates" = "testing-lost-updates/how-do-you-test-for-lost-updates.md"},
    {"Follow a risk based approach" = "testing-lost-updates/follow-a-risk-based-approach.md"},
    {"Concurrency controls" = "testing-lost-updates/concurrency-controls.md"},
    {"Locking" = "testing-lost-updates/locking.md"},
    {"Write and execute tests" = "testing-lost-updates/write-and-execute-tests.md"},
    {"Example test scripts" = "testing-lost-updates/example-test-scripts.md"},
    {"Further reading" = "testing-lost-updates/further-reading.md"},
  ]},
  {"Coding Standard Template" = [
    {"Introduction" = "coding-standard-template/introduction.md"},
    {"Use a brief heading to describe the standards" = "coding-standard-template/use-a-brief-heading-to-describe-the-standards.md"},
    {"Exceptions prove the rule" = "coding-standard-template/exceptions-prove-the-rule.md"},
    {"Good practice checklists" = "coding-standard-template/good-practice-checklists.md"},
  ]},
]
# Markdown extensions at project level
[project.markdown_extensions.admonition]
[project.markdown_extensions.footnotes]

[project.markdown_extensions.pymdownx.details]
[project.markdown_extensions.pymdownx.highlight]
anchor_linenums = true
line_spans = "__span"
pygments_lang_class = true

[project.markdown_extensions.pymdownx.inlinehilite]

[project.markdown_extensions.pymdownx.snippets]
check_paths = true

[project.markdown_extensions.pymdownx.tabbed]
alternate_style = true

[project.markdown_extensions.pymdownx.superfences]
custom_fences = [
  {name = "mermaid", class = "mermaid", format = "pymdownx.superfences.fence_code_format"}
]

# Theme configuration
[project.theme]
name = "modern"
custom_dir = "doc/overrides"
logo = "assets/logo.png"
favicon = "assets/favicon.ico"

# Theme features - must be at theme level, not nested
features = [
  "navigation.footer",
  "navigation.path",
  "navigation.instant",
  "navigation.top",
  "content.action.edit",
  "content.action.view",
  "content.code.copy",
  "search.highlight"
]

[[project.theme.palette]]
scheme = "default"
toggle.icon = "lucide/sun"
toggle.name = "Switch to dark mode"

[[project.theme.palette]]
scheme = "slate"
toggle.icon = "lucide/moon"
toggle.name = "Switch to light mode"

[project.theme.icon]
repo = "fontawesome/brands/github"

[project.theme.font]
text = "Rubik"

# Cookie consent configuration
[project.extra.consent]
title = "Cookie consent"
description = """
We use cookies to optimise site functionality and give you the best
possible experience, recognise your repeated visits and preferences, as
well as to measure the effectiveness of our site and whether
users find what they're searching for. With your consent, you're helping
us to make our site better.
"""

# Cookie consent cookies - using dict format to avoid 'list' error
[project.extra.consent.cookies]
analytics = {name = "Simple Analytics", checked = true}

# Analytics configuration
[project.extra.analytics]
provider = "simple"