[GitHub] [pulsar] Anonymitaet created a discussion: [feat][workflow] add automatic grammar check for code examples in docs

[GitBox <gi...@apache.org>]

GitHub user Anonymitaet created a discussion: [feat][workflow] add automatic grammar check for code examples in docs

## ❓ Issue

Currently, as a core part of docs, code examples (snippets) are added in a widespread manner.

Sometimes there are issues in the code examples (e.g., grammar mistakes, indention inconsistencies, etc.) but we do not know until users raise them up. 

At intervals, we have PRs focusing on fixing these errors, which is not worth the effort and can be optimized by automatic workflow.

## 🤔 Solution

Does it make sense to add automatic grammar check for code examples in Pulsar docs?

Along with markdown changes, grammar of code samples are checked in CI/CD process as well.

In this way, PR author can fix errors in a timely manner and ensure that all content is accurate throughout docs.

## 💡 Example and Referneces

In Rustdoc, code examples are complied as well to ensure that the code is workable. 

```
# Examples
  ```rust
assert_eq!(2 + 2, 4);
  ```.
```

Code test cases are generated to test the code above.

```
#![allow(unused)]

fn main() {
   #[allow(non_snake_case)]
   fn _doctest_main__some_unique_name() {
       assert_eq!(2 + 2, 4);
   }
   _doctest_main__some_unique_name()
}
```

Referneces:
- https://doc.rust-lang.org/rustdoc/write-documentation/documentation-tests.html
- https://github.com/rust-lang/rust/tree/master/src/librustdoc
- https://www.phodal.com/blog/api-ducumentation-design-dsl-base/ (in Chinese. Sorry I don't find similar resources in English)

cc @momo-jun @DaveDuggins @D-2-Ed



GitHub link: https://github.com/apache/pulsar/discussions/19659

----
This is an automatically sent email for commits@pulsar.apache.org.
To unsubscribe, please send an email to: commits-unsubscribe@pulsar.apache.org

[GitHub] [pulsar] Anonymitaet added a comment to the discussion: [feat][workflow] add automatic grammar check for code examples in docs

[GitBox <gi...@apache.org>]

GitHub user Anonymitaet added a comment to the discussion: [feat][workflow] add automatic grammar check for code examples in docs

@labuladong thanks! I mean adding grammar checks for code examples (at least we can clear up basic mistakes), like VS Code plugins will remind users if they have grammar mistakes when coding. So can we add a similar automatic check to the doc contribution process? Is it implementable from a technical perspective?

GitHub link: https://github.com/apache/pulsar/discussions/19659#discussioncomment-5173068

----
This is an automatically sent email for commits@pulsar.apache.org.
To unsubscribe, please send an email to: commits-unsubscribe@pulsar.apache.org

[GitHub] [pulsar] labuladong added a comment to the discussion: [feat][workflow] add automatic grammar check for code examples in docs

[GitBox <gi...@apache.org>]

GitHub user labuladong added a comment to the discussion: [feat][workflow] add automatic grammar check for code examples in docs

I don't think Java code can be tested online. On the other hand, most code examples in Pulsar doc are incomplete for running. But I think we can do the check for markdown links.

GitHub link: https://github.com/apache/pulsar/discussions/19659#discussioncomment-5145267

----
This is an automatically sent email for commits@pulsar.apache.org.
To unsubscribe, please send an email to: commits-unsubscribe@pulsar.apache.org

[GitHub] [pulsar] momo-jun added a comment to the discussion: [feat][workflow] add automatic grammar check for code examples in docs

[GitBox <gi...@apache.org>]

GitHub user momo-jun added a comment to the discussion: [feat][workflow] add automatic grammar check for code examples in docs

Auto-testing code examples in the docs is a great idea. @Anonymitaet, thanks for raising it. We need it definitely.
Can we do it together with the local build? Integrating the process into CI/CD may occupy much resources I guess.
CC @labuladong @tisonkun 

GitHub link: https://github.com/apache/pulsar/discussions/19659#discussioncomment-5140534

----
This is an automatically sent email for commits@pulsar.apache.org.
To unsubscribe, please send an email to: commits-unsubscribe@pulsar.apache.org

[GitHub] [pulsar] labuladong added a comment to the discussion: [feat][workflow] add automatic grammar check for code examples in docs

[GitBox <gi...@apache.org>]

GitHub user labuladong added a comment to the discussion: [feat][workflow] add automatic grammar check for code examples in docs

Actually, there's no similar automatic check for code unless the code is in an editor like vscode and has a total project context. Rust doc can only run small code snippets, too. So I think it's not implementable.

GitHub link: https://github.com/apache/pulsar/discussions/19659#discussioncomment-5174995

----
This is an automatically sent email for commits@pulsar.apache.org.
To unsubscribe, please send an email to: commits-unsubscribe@pulsar.apache.org