diff --git a/.github/workflows/link_validation.yaml b/.github/workflows/link_validation.yaml new file mode 100644 index 000000000..e0bcbfae7 --- /dev/null +++ b/.github/workflows/link_validation.yaml @@ -0,0 +1,29 @@ +name: validate-links + +on: + push: + branches: + - v* + tags: + - v* + pull_request: + branches: + - v* +jobs: + validate: + runs-on: ubuntu-latest + env: + PYTHON_VER: 3.7 + steps: + - uses: actions/checkout@v2 + - name: Set up Python ${{ env.PYTHON_VER }} + uses: actions/setup-python@v2 + with: + python-version: ${{ env.PYTHON_VER }} + - name: Install dependencies + run: | + python3 -m pip install --upgrade pip + pip3 install setuptools wheel twine tox mechanical-markdown + - name: Check Markdown Files + run: | + for name in `find . -name "*.md"`; do echo -e "------\n$name" ; mm.py -l $name || exit 1 ;done diff --git a/.gitmodules b/.gitmodules index be99ad3b7..3d8a47fd8 100644 --- a/.gitmodules +++ b/.gitmodules @@ -10,3 +10,7 @@ [submodule "sdkdocs/dotnet"] path = sdkdocs/dotnet url = https://github.com/dapr/dotnet-sdk.git +[submodule "translations/docs-zh"] + path = translations/docs-zh + url = https://github.com/dapr/docs-zh.git + branch = v1.0_content diff --git a/daprdocs/assets/scss/_code.scss b/daprdocs/assets/scss/_code.scss index 1c20542c6..dd05e51bf 100644 --- a/daprdocs/assets/scss/_code.scss +++ b/daprdocs/assets/scss/_code.scss @@ -47,6 +47,8 @@ margin: 0rem 0; padding: 0rem; + margin-bottom: 2rem; + max-width: 100%; pre { diff --git a/daprdocs/config.toml b/daprdocs/config.toml index 3dccca2e7..8348915d3 100644 --- a/daprdocs/config.toml +++ b/daprdocs/config.toml @@ -10,6 +10,18 @@ enableGitInfo = true # Language Configuration languageCode = "en-us" +[languages] + [languages.en] + title = "Dapr Docs" + weight = 1 + contentDir = "content/en" + languageName = "English" + [languages.zh-hans] + title = "Dapr 文档库" + weight = 2 + contentDir = "content/zh-hans" + languageName = "简体中文" + # Disable categories & tags disableKinds = ["taxonomy", "term"] @@ -22,6 +34,7 @@ id = "UA-149338238-3" [[module.mounts]] source = "content/en" target = "content" + lang = "en" [[module.mounts]] source = "static" target = "static" @@ -37,21 +50,48 @@ id = "UA-149338238-3" [[module.mounts]] source = "archetypes" target = "archetypes" + [[module.mounts]] source = "../sdkdocs/python/daprdocs/content/en/python-sdk-docs" target = "content/developing-applications/sdks/python" + lang = "en" [[module.mounts]] source = "../sdkdocs/python/daprdocs/content/en/python-sdk-contributing" target = "content/contributing/" + lang = "en" [[module.mounts]] source = "../sdkdocs/php/daprdocs/content/en/php-sdk-docs" target = "content/developing-applications/sdks/php" + lang = "en" [[module.mounts]] source = "../sdkdocs/dotnet/daprdocs/content/en/dotnet-sdk-docs" target = "content/developing-applications/sdks/dotnet" + lang = "en" [[module.mounts]] source = "../sdkdocs/dotnet/daprdocs/content/en/dotnet-sdk-contributing" target = "content/contributing/" + lang = "en" + + [[module.mounts]] + source = "../translations/docs-zh/content/zh-hans" + target = "content" + lang = "zh-hans" + [[module.mounts]] + source = "../translations/docs-zh/content/contributing" + target = "content/contributing/" + lang = "zh-hans" + [[module.mounts]] + source = "../translations/docs-zh/content/sdks_python" + target = "content/developing-applications/sdks/python" + lang = "zh-hans" + [[module.mounts]] + source = "../translations/docs-zh/content/sdks_php" + target = "content/developing-applications/sdks/php" + lang = "zh-hans" + [[module.mounts]] + source = "../translations/docs-zh/content/sdks_dotnet" + target = "content/developing-applications/sdks/dotnet" + lang = "zh-hans" # Markdown Engine - Allow inline html [markup] diff --git a/daprdocs/content/en/concepts/building-blocks-concept.md b/daprdocs/content/en/concepts/building-blocks-concept.md index 76a02addd..111c8fc16 100644 --- a/daprdocs/content/en/concepts/building-blocks-concept.md +++ b/daprdocs/content/en/concepts/building-blocks-concept.md @@ -24,6 +24,6 @@ The following are the building blocks provided by Dapr: | [**State management**]({{}}) | `/v1.0/state` | Application state is anything an application wants to preserve beyond a single session. Dapr provides a key/value-based state API with pluggable state stores for persistence. | [**Publish and subscribe**]({{}}) | `/v1.0/publish` `/v1.0/subscribe`| Pub/Sub is a loosely coupled messaging pattern where senders (or publishers) publishes messages to a topic, to which subscribers subscribe. Dapr supports the pub/sub pattern between applications. | [**Resource bindings**]({{}}) | `/v1.0/bindings` | A binding provides a bi-directional connection to an external cloud/on-premise service or system. Dapr allows you to invoke the external service through the Dapr binding API, and it allows your application to be triggered by events sent by the connected service. -| [**Actors**]({{}}) | `/v1.0/actors` | An actor is an isolated, independent unit of compute and state with single-threaded execution. Dapr provides an actor implementation based on the Virtual Actor pattern which provides a single-threaded programming model and where actors are garbage collected when not in use. See * [Actor Overview](./actors#understanding-actors) +| [**Actors**]({{}}) | `/v1.0/actors` | An actor is an isolated, independent unit of compute and state with single-threaded execution. Dapr provides an actor implementation based on the Virtual Actor pattern which provides a single-threaded programming model and where actors are garbage collected when not in use. See [Actor Overview](./actors#understanding-actors) | [**Observability**]({{}}) | `N/A` | Dapr system components and runtime emit metrics, logs, and traces to debug, operate and monitor Dapr system services, components and user applications. | [**Secrets**]({{}}) | `/v1.0/secrets` | Dapr offers a secrets building block API and integrates with secret stores such as Azure Key Vault and Kubernetes to store the secrets. Service code can call the secrets API to retrieve secrets out of the Dapr supported secret stores. diff --git a/daprdocs/content/en/concepts/faq.md b/daprdocs/content/en/concepts/faq.md index aaad28c0b..8106ef646 100644 --- a/daprdocs/content/en/concepts/faq.md +++ b/daprdocs/content/en/concepts/faq.md @@ -36,7 +36,7 @@ The Dapr project is focused on performance due to the inherent discussion of Dap ### What is the relationship between Dapr, Orleans and Service Fabric Reliable Actors? The actors in Dapr are based on the same virtual actor concept that [Orleans](https://www.microsoft.com/research/project/orleans-virtual-actors/) started, meaning that they are activated when called and deactivated after a period of time. If you are familiar with Orleans, Dapr C# actors will be familiar. Dapr C# actors are based on [Service Fabric Reliable Actors](https://docs.microsoft.com/azure/service-fabric/service-fabric-reliable-actors-introduction) (which also came from Orleans) and enable you to take Reliable Actors in Service Fabric and migrate them to other hosting platforms such as Kubernetes or other on-premise environments. -Also Dapr is about more than just actors. It provides you with a set of best practice building blocks to build into any microservices application. See [Dapr overview](https://github.com/dapr/docs/blob/master/overview/README.md). +Also Dapr is about more than just actors. It provides you with a set of best practice building blocks to build into any microservices application. See [Dapr overview]({{< ref overview.md >}}). ### Differences between Dapr from an actor framework diff --git a/daprdocs/content/en/concepts/security-concept.md b/daprdocs/content/en/concepts/security-concept.md index c130d0fe4..dd097337e 100644 --- a/daprdocs/content/en/concepts/security-concept.md +++ b/daprdocs/content/en/concepts/security-concept.md @@ -11,7 +11,7 @@ This article addresses multiple security considerations when using Dapr in a dis Several of the areas above are addressed through encryption of data in transit. One of the security mechanisms that Dapr employs for encrypting data in transit is [mutual authentication TLS](https://en.wikipedia.org/wiki/Mutual_authentication) or mTLS. mTLS offers a few key features for network traffic inside your application: -- Two way authentication - the client proving its identify to the server, and vice-versa +- Two way authentication - the client proving its identity to the server, and vice-versa - An encrypted channel for all in-flight communication, after two-way authentication is established Mutual TLS is useful in almost all scenarios, but especially so for systems subject to regulations such as [HIPAA](https://en.wikipedia.org/wiki/Health_Insurance_Portability_and_Accountability_Act) and [PCI](https://en.wikipedia.org/wiki/Payment_Card_Industry_Data_Security_Standard). diff --git a/daprdocs/content/en/contributing/contributing-docs.md b/daprdocs/content/en/contributing/contributing-docs.md index fd671fd02..3fa66cbe5 100644 --- a/daprdocs/content/en/contributing/contributing-docs.md +++ b/daprdocs/content/en/contributing/contributing-docs.md @@ -22,7 +22,7 @@ Follow the instructions in the repository [README.md](https://github.com/dapr/do The Dapr docs handles branching differently than most code repositories. Instead of having a `master` or `main` branch, every branch is labeled to match the major and minor version of a runtime release. For the full list visit the [Docs repo](https://github.com/dapr/docs#branch-guidance) -Overall, all updates should go into the docs branch for the latest release of Dapr. You can find this directly at https://github.com/dapr/docs, as the latest release will be the default branch. For any docs changes that are applicable to a release candidate or a pre-release version of the docs, make your changes into that particular branch. +Overall, all updates should go into the docs branch for the latest release of Dapr. You can find this directly at [https://github.com/dapr/docs](https://github.com/dapr/docs), as the latest release will be the default branch. For any docs changes that are applicable to a release candidate or a pre-release version of the docs, make your changes into that particular branch. For example, if you are fixing a typo, adding notes, or clarifying a point, make your changes into the default Dapr branch. If you are documenting an upcoming change to a component or the runtime, make your changes to the pre-release branch. Branches can be found in the [Docs repo](https://github.com/dapr/docs#branch-guidance) @@ -232,3 +232,32 @@ The shortcode would be: ### References - [Docsy authoring guide](https://www.docsy.dev/docs/adding-content/) + +## Translations + +The Dapr Docs supports adding language translations into the docs using git submodules and Hugo's built in language support. + +You can find an example PR of adding Chinese language support in [PR 1286](https://github.com/dapr/docs/pull/1286). + +Steps to add a language: +- Open an issue in the Docs repo requesting to create a new language-specific docs repo +- Once created, create a git submodule within the docs repo: + ```sh + git submodule add translations/ + ``` +- Add a language entry within `daprdocs/config.toml`: + ```toml + [languages.] + title = "Dapr Docs" + weight = 3 + contentDir = "content/" + languageName = "" + ``` +- Create a mount within `daprdocs/config.toml`: + ```toml + [[module.mounts]] + source = "../translations/docs-/content/" + target = "content" + lang = "" + ``` +- Repeat above step as necessary for all other translation directories \ No newline at end of file diff --git a/daprdocs/content/en/contributing/contributing-overview.md b/daprdocs/content/en/contributing/contributing-overview.md index cc9c81cd2..c8b72c60b 100644 --- a/daprdocs/content/en/contributing/contributing-overview.md +++ b/daprdocs/content/en/contributing/contributing-overview.md @@ -38,7 +38,7 @@ Before you submit an issue, make sure you've checked the following: - 👎 down-vote 1. For bugs - Check it's not an environment issue. For example, if running on Kubernetes, make sure prerequisites are in place. (state stores, bindings, etc.) - - You have as much data as possible. This usually comes in the form of logs and/or stacktrace. If running on Kubernetes or other environment, look at the logs of the Dapr services (runtime, operator, placement service). More details on how to get logs can be found [here](https://github.com/dapr/docs/tree/master/best-practices/troubleshooting/logs.md). + - You have as much data as possible. This usually comes in the form of logs and/or stacktrace. If running on Kubernetes or other environment, look at the logs of the Dapr services (runtime, operator, placement service). More details on how to get logs can be found [here]({{< ref "logs-troubleshooting.md" >}}). 1. For proposals - Many changes to the Dapr runtime may require changes to the API. In that case, the best place to discuss the potential feature is the main [Dapr repo](https://github.com/dapr/dapr). - Other examples could include bindings, state stores or entirely new components. diff --git a/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md b/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md index 463d4f319..affecfbf8 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md +++ b/daprdocs/content/en/developing-applications/building-blocks/pubsub/howto-publish-subscribe.md @@ -221,7 +221,7 @@ $app->post('/dsstatus', function( $app->start(); ``` -After creating `app1.php`, and with the [SDK installed](https://github.com/dapr/php-sdk/blob/main/docs/getting-started.md), +After creating `app1.php`, and with the [SDK installed](https://docs.dapr.io/developing-applications/sdks/php/), go ahead and start the app: ```bash diff --git a/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md b/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md index 0161e0255..284829727 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md @@ -15,7 +15,7 @@ When using state management your application can leverage features that would ot - Distributed concurrency and data consistency - Bulk [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) operations -Your application can used Dapr's state management API to save and read key/value pairs using a state store component, as shown in the diagram below. For example, by using HTTP POST you can save key/value pairs and by using HTTP GET you can read a key and have its value returned. +Your application can use Dapr's state management API to save and read key/value pairs using a state store component, as shown in the diagram below. For example, by using HTTP POST you can save key/value pairs and by using HTTP GET you can read a key and have its value returned. diff --git a/daprdocs/content/en/developing-applications/ides/intellij.md b/daprdocs/content/en/developing-applications/ides/intellij.md index e7facc35f..4bba54732 100644 --- a/daprdocs/content/en/developing-applications/ides/intellij.md +++ b/daprdocs/content/en/developing-applications/ides/intellij.md @@ -71,7 +71,7 @@ Add a new `` entry: