From eb84902480f1c47d68daa689db3072bea006b461 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A2u=20Cao?= <842+raucao@users.noreply.github.com> Date: Mon, 5 Aug 2024 13:51:17 +0200 Subject: [PATCH] Update contributing/docs.md --- docs/contributing/docs.md | 113 ++++++-------------------------------- 1 file changed, 18 insertions(+), 95 deletions(-) diff --git a/docs/contributing/docs.md b/docs/contributing/docs.md index 4ab5733d1..9f2384561 100644 --- a/docs/contributing/docs.md +++ b/docs/contributing/docs.md @@ -1,112 +1,35 @@ -::: danger DEPRECATED -Needs a complete rewrite for the new TypeDoc + VitePress setup -::: - # Documentation -The documentation for remoteStorage.js is generated from -[reStructuredText](http://docutils.sourceforge.net/rst.html) files in -the `doc/` folder, as well as [TypeDoc](https://typedoc.org/) code -comments, which are being pulled in via special declarations in those -files. - -We use [Sphinx](http://www.sphinx-doc.org/) to generate the -documentation website, and the -[sphinx-js](https://pypi.python.org/pypi/sphinx-js/) extension for -handling the TypeDoc part. - -## How to write reStructuredText and TypeDoc - -For learning both the basics and advances features of reStructuredText, -we highly recommend the [reStructuredText -Primer](http://www.sphinx-doc.org/en/stable/rest.html) on the Sphinx -website. - -For TypeDoc, you can find guides as well as a detailed reference [on the -project\'s website](https://typedoc.org/). - -## Automatic builds and publishing - -The documentation is published via [Read the -Docs](https://readthedocs.org/). Whenever the Git repository\'s `master` -branch is pushed to GitHub, RTD will automatically build a new version -of the site and publish it to -[remotestoragejs.readthedocs.io](https://remotestoragejs.readthedocs.io). - -This means that if you want to contribute to the documentation, you -don\'t necessarily have to set up Sphinx and sphinx-js locally -(especially for small changes). However, if you want to preview what -your local changes look like when they are rendered as HTML, you will -have to set up local builds first. - -## How to build the docs on your machine - -### Setup - -1. [Install Python and PIP](https://pip.pypa.io/en/stable/installing/) - (likely already installed) +The documentation for remoteStorage.js comes from two different sources: -2. Install sphinx-js and extensions (from repository root): +1. Markdown documents in the `docs/` folder for normal pages +2. TypeDoc comments in the source code, which are also rendered as Markdown pages when updating the website - ```sh - $ pip install -r doc/requirements.txt - ``` +The pages are then transformed into a functional website using [VitePress](https://vitepress.dev/). Please refer to the VitePress documentation for available [Markdown extensions](https://vitepress.dev/guide/markdown), [configuring the sidebar menu](https://vitepress.dev/reference/default-theme-sidebar), and more. -3. Install TypeScript and TypeDoc globally (so Sphinx can use them): +## Contributing - ```sh - $ npm -g install typescript typedoc - ``` +You can just edit any Markdown document or TypeDoc comment and propose the changes in a new pull request. No need to build the docs locally if you don't want to. -### Build +## Local preview -Run the following command to automatically watch and build the -documentation: +There is a local setup in this repository for previewing the rendered output. A live preview with automatic reloading upon changes can be started using this command: ```sh -$ npm run autobuild-docs +npm run docs:dev ``` -This will start a web server, serving rendered HTML docs on -. +If you want to edit TypeDoc comments and have the changes appear in your local preview, then you also have to run this command: -::: hint -::: title -Hint -::: - -The autobuild cannot watch for changes in TypeDoc comments as of now, so -you will need to re-run the command, or change something in a `.rst` -file in order for code documentation changes to be re-built. -::: - -## How to build the docs using ReadTheDocs\' Docker image - -This is useful for troubleshooting when the ReadTheDocs build is -failing. - -### Setup - -1. [Install Docker](https://docs.docker.com/get-docker/) - -2. Pull the latest version of `readthedocs/build` image with the - `latest` tag from Docker Hub: - - ```sh - $ docker pull readthedocs/build:latest - ``` - -### Build +```sh +typedoc --watch +``` -1. Enter a `bash` session while attaching this project as a volume: +## Publishing - ```sh - $ docker run --rm -it -v ${PWD}:/app readthedocs/build:latest bash - ``` +The rs.js documentation on https://remotestorage.io/rs.js/docs/ is published from the [remotestorage/website](https://github.com/remotestorage/website/) repo. This repository is included as a submodule in the website repo, so that there is no duplication of content or builds. -2. Run the `build-with-conda.sh` script to setup conda environment and - build the docs like ReadTheDocs: +This means that any merged rs.js docs changes currently require a manual update of the website repository in order to be visible in the public docs. - ```sh - $ /app/doc/build-with-conda.sh - ``` +> [!NOTE] +> The process of updating the website automatically, whenever rs.js docs changes are merged, will be automated soon