Merge pull request #1317 from remotestorage/docs/contributing-docs

Update contributing/docs.md

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
-<http://localhost:8000>.
+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