Skip to content

Conversation

taminomara
Copy link
Contributor

I've been working on documentation update.

I'm using Sphinx with Markdown (MySt) and my Lua plugin to automatically document emmyrc options and built-in types.

This is a very much work in progress, but all automation is done, what's left is to migrate current markdown documents. The last commit in this PR gets automatically deployed to https://taminomara.github.io/emmylua-analyzer-rust/en/

Note: language toggle works, but translation tables for Chinese are empty, so both versions are identical. I'll try to fill some of them from existing documents, but some help from community would be very much appreciated.

How's this better than current solution

  1. Parts of documentation are generated automatically. Any changes to emmyrc schema and builtin types will be applied to corresponding pages.
  2. Translation is stored in .po files, meaning that it's easier to keep English and Chinese versions in sync.
  3. In theory, we'll be able to reuse translation database when building editor extensions.

@taminomara taminomara marked this pull request as draft August 20, 2025 17:18
@xuhuanzy
Copy link
Member

Document translation implementation needs further research, and I prefer using VitePress for the documentation website because it offers a better browsing experience.

@xuhuanzy
Copy link
Member

In order to ensure the documentation is easy to use, we must manually add a large number of examples and explanations. Simply generating the documentation from the source code is not feasible.

@taminomara
Copy link
Contributor Author

Simply generating the documentation from the source code is not feasible.

Yes, sure. What I mean is that frequently changing things like config options and diagnostic codes can be documented in Rust source, and Sphinx will embed this documentation into markdown. This will help to keep everything up to date.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants