diff --git a/.gitignore b/.gitignore index 0443cdf..b531afb 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,9 @@ ## Ignore Visual Studio temporary files, build results, and ## files generated by popular Visual Studio add-ons. +docs/api +docs/_site + # User-specific files *.suo *.user diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 9c04672..7f7e84e 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -129,3 +129,29 @@ deploy-release: - if: $CI_COMMIT_TAG != null script: - dotnet nuget push -k $NUGET_APIKEY -s https://api.nuget.org/v3/index.json --skip-duplicate artifacts/*.nupkg + + + +publish-docs: + variables: + DOCFX_SOURCE_REPOSITORY_URL: "https://github.com/AM-WD/AMWD.Protocols.Modbus" + stage: deploy + tags: + - docker + - lnx + - server + rules: + - if: $CI_COMMIT_TAG != null + before_script: + - apt-get update + - apt-get -y install zip unzip + - dotnet tool install docfx --tool-path /dotnet-tools + script: + # Build the docs + - dotnet build -c Release --nologo + - /dotnet-tools/docfx metadata docs/docfx.json + - /dotnet-tools/docfx build docs/docfx.json + # Deploy the docs + - cd docs/_site + - zip -r ../docs.zip * + - curl --user "$DOCS_DEPLOY_USER:$DOCS_DEPLOY_PASS" -F docs=modbus -F dump=@../docs.zip "$DOCS_DEPLOY_URL" \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 0581b69..a68b3d6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] -_nothing changed yet_ +### Added + +- New automatic documentation generation using docfx. + +### Changed + +- Reorganized folder structure to allow documentation generation. ## [v0.4.2] (2025-02-07) diff --git a/README.md b/README.md index 236f5c8..981bf95 100644 --- a/README.md +++ b/README.md @@ -39,13 +39,12 @@ It uses a specific TCP connection implementation and plugs all things from the C Published under [MIT License] (see [choose a license]) [![Buy me a Coffee](https://shields.io/badge/PayPal-Buy_me_a_Coffee-yellow?style=flat&logo=paypal)](https://link.am-wd.de/donate) -[![built with Codeium](https://codeium.com/badges/main)](https://link.am-wd.de/codeium) [see here]: https://github.com/andreasAMmueller/Modbus -[Common]: AMWD.Protocols.Modbus.Common/README.md -[Serial]: AMWD.Protocols.Modbus.Serial/README.md -[TCP]: AMWD.Protocols.Modbus.Tcp/README.md +[Common]: src/AMWD.Protocols.Modbus.Common/README.md +[Serial]: src/AMWD.Protocols.Modbus.Serial/README.md +[TCP]: src/AMWD.Protocols.Modbus.Tcp/README.md [MIT License]: LICENSE.txt [choose a license]: https://choosealicense.com/licenses/mit/ diff --git a/docs/articles/getting-started.md b/docs/articles/getting-started.md new file mode 100644 index 0000000..8b3a794 --- /dev/null +++ b/docs/articles/getting-started.md @@ -0,0 +1 @@ +# Getting Started \ No newline at end of file diff --git a/docs/articles/introduction.md b/docs/articles/introduction.md new file mode 100644 index 0000000..f6ecaa6 --- /dev/null +++ b/docs/articles/introduction.md @@ -0,0 +1 @@ +# Introduction \ No newline at end of file diff --git a/docs/articles/toc.yml b/docs/articles/toc.yml new file mode 100644 index 0000000..d3663b9 --- /dev/null +++ b/docs/articles/toc.yml @@ -0,0 +1,4 @@ +- name: Introduction + href: introduction.md +- name: Getting Started + href: getting-started.md \ No newline at end of file diff --git a/docs/docfx.json b/docs/docfx.json new file mode 100644 index 0000000..7b0d1d6 --- /dev/null +++ b/docs/docfx.json @@ -0,0 +1,63 @@ +{ + "$schema": "https://raw.githubusercontent.com/dotnet/docfx/main/schemas/docfx.schema.json", + "metadata": [ + { + "src": [ + { + "src": "../", + "files": [ + "src/AMWD.Protocols.Modbus.Common/bin/Release/netstandard2.0/amwd-modbus-common.dll", + "src/AMWD.Protocols.Modbus.Serial/bin/Release/netstandard2.0/amwd-modbus-serial.dll", + "src/AMWD.Protocols.Modbus.Tcp/bin/Release/netstandard2.0/amwd-modbus-tcp.dll" + ] + } + ], + "dest": "api", + "outputFormat": "apiPage" + } + ], + "build": { + "content": [ + { + "files": [ "**/*.{md,yml}" ], + "exclude": [ "_site/**", "obj/**" ] + } + ], + "resource": [ + { + "files": [ "images/**" ], + "exclude": [ "_site/**", "obj/**" ] + } + ], + "output": "_site", + "template": [ "default", "modern", "templates/amwd" ], + "postProcessors": ["ExtractSearchIndex"], + "globalMetadata": { + "_appName": "Protocol for .NET", + "_appTitle": "Modbus Protocol for .NET", + "_appFooter": "© AM.WD — Docs generated using docfx.", + "_appLogoPath": "images/logo.svg", + "_appFaviconPath": "images/favicon.ico", + "_disableBreadcrumb": true, + "_disableContribution": true, + "_enableSearch": true, + "_enableNewTab": true, + "pdf": false + }, + "markdownEngineName": "markdig", + "markdownEngineProperties": { + "alerts": { + "TODO": "alert alert-secondary" + } + }, + "sitemap": { + "baseUrl": "https://docs.am-wd.de/modbus", + "priority": 0.5, + "changefreq": "weekly" + }, + "noLangKeyword": false, + "keepFileLink": false, + "cleanupCacheHistory": false, + "disableGitFeatures": true + } +} \ No newline at end of file diff --git a/docs/images/favicon.ico b/docs/images/favicon.ico new file mode 100644 index 0000000..0ccb7d7 Binary files /dev/null and b/docs/images/favicon.ico differ diff --git a/docs/images/logo.svg b/docs/images/logo.svg new file mode 100644 index 0000000..79775eb --- /dev/null +++ b/docs/images/logo.svg @@ -0,0 +1,168 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..c7ee121 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,26 @@ +--- +_layout: landing +--- + +# Modbus Protocol for .NET + +This library implements the basic Modbus protocol specified at [modbus.org](https://modbus.org/tech.php). + +The aim was to include all necessary steps to have a fully working client, which is capable of the common protocol versions. + + +## NuGet packages + +Here is an overview of the latest packages. + +| Package Url | Version | Short description | +|-------------|---------|-------------------| +| [AMWD.Protocols.Modbus.Common] | ![NuGet Version: Common](https://img.shields.io/nuget/v/AMWD.Protocols.Modbus.Common?style=flat-square&logo=nuget) | Common data for Modbus protocol. | +| [AMWD.Protocols.Modbus.Serial] | ![NuGet Version: Serial](https://img.shields.io/nuget/v/AMWD.Protocols.Modbus.Serial?style=flat-square&logo=nuget) | Implementation of the Modbus protocol communicating via serial line using RTU or ASCII encoding. | +| [AMWD.Protocols.Modbus.Tcp] | ![NuGet Version: TCP](https://img.shields.io/nuget/v/AMWD.Protocols.Modbus.Tcp?style=flat-square&logo=nuget) | Implementation of the Modbus protocol communicating via TCP. | + + + +[AMWD.Protocols.Modbus.Common]: https://www.nuget.org/packages/AMWD.Protocols.Modbus.Common +[AMWD.Protocols.Modbus.Serial]: https://www.nuget.org/packages/AMWD.Protocols.Modbus.Serial +[AMWD.Protocols.Modbus.Tcp]: https://www.nuget.org/packages/AMWD.Protocols.Modbus.Tcp diff --git a/docs/templates/amwd/public/main.css b/docs/templates/amwd/public/main.css new file mode 100644 index 0000000..057f8d0 --- /dev/null +++ b/docs/templates/amwd/public/main.css @@ -0,0 +1,3 @@ +#logo { + margin-right: 8px; +} \ No newline at end of file diff --git a/docs/toc.yml b/docs/toc.yml new file mode 100644 index 0000000..b7532c4 --- /dev/null +++ b/docs/toc.yml @@ -0,0 +1,4 @@ +- name: API + href: api/ +- name: Articles + href: articles/