Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: live preview (without VS Code) #181

Closed
AlexanderLanin opened this issue Jan 17, 2025 · 3 comments · Fixed by #281
Closed

docs: live preview (without VS Code) #181

AlexanderLanin opened this issue Jan 17, 2025 · 3 comments · Fixed by #281
Assignees
Labels
docs-as-code good first issue Good for newcomers infrastructure General Score infrastructure topics

Comments

@AlexanderLanin
Copy link
Member

AlexanderLanin commented Jan 17, 2025

Provide the ability of a live preview outside of VS Code.
People are using different IDEs, and we cannot do a full integration into all of them.
But we can provide a generic preview ability, e.g. sphinx-autobuild.

Task:

  • document why we use sphinx-autobuild (or some alternative)
  • implement solution
@AlexanderLanin AlexanderLanin added infrastructure General Score infrastructure topics docs-as-code labels Jan 21, 2025
@AlexanderLanin AlexanderLanin changed the title docs: live preview docs: live preview (without VS Code) Jan 22, 2025
@AlexanderLanin AlexanderLanin added the good first issue Good for newcomers label Jan 28, 2025
@hoe-jo
Copy link
Contributor

hoe-jo commented Jan 29, 2025

We also could provide additional configs, we are working on a configuration for Clion

@AlexanderLanin
Copy link
Member Author

We also could provide additional configs, we are working on a configuration for Clion

Let's create a separate issue for CLion if we want to support that.

@nicu1989 nicu1989 self-assigned this Feb 4, 2025
@nicu1989 nicu1989 moved this from Todo to In Progress in Operational (Tooling/Infrastructure) Feb 4, 2025
@nicu1989
Copy link
Contributor

nicu1989 commented Feb 4, 2025

I have checked some of the tools used for live preview and did a comparison:

Feature Sphinx-autobuild Docutils Grip
Live Preview Provides live-reloading of HTML output when .rst files are modified. It monitors changes and automatically rebuilds the documentation. Does not offer live preview capabilities. Users need to manually run commands like rst2html to convert .rst files to HTML and then open the output in a browser. Primarily designed for Markdown files and does not natively support .rst. While it offers live preview for Markdown, it lacks built-in support for .rst live preview.
Ease of Use Automatic rebuilding on save. Requires manual steps for each update: converting .rst files to the desired format and viewing them separately. Easy to use for Markdown files with live preview, but not suitable for .rst without additional configuration or tools.
Additional Features Integrates with Sphinx, allowing the use of Sphinx extensions and themes during live preview. Focuses on converting .rst to various formats. Offers live preview and rendering for Markdown, but lacks support for .rst features and Sphinx integrations.

The best way to go is to use sphinx-autobuild from devcontainer/venv . I will create a PR that documents how to use it and implement the other required changes.

@nicu1989 nicu1989 moved this from In Progress to Done in Operational (Tooling/Infrastructure) Feb 7, 2025
@AlexanderLanin AlexanderLanin linked a pull request Feb 7, 2025 that will close this issue
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs-as-code good first issue Good for newcomers infrastructure General Score infrastructure topics
Projects
Development

Successfully merging a pull request may close this issue.

3 participants