|
1 | | -::: danger DEPRECATED |
2 | | -Needs a complete rewrite for the new TypeDoc + VitePress setup |
3 | | -::: |
4 | | - |
5 | 1 | # Documentation |
6 | 2 |
|
7 | | -The documentation for remoteStorage.js is generated from |
8 | | -[reStructuredText](http://docutils.sourceforge.net/rst.html) files in |
9 | | -the `doc/` folder, as well as [TypeDoc](https://typedoc.org/) code |
10 | | -comments, which are being pulled in via special declarations in those |
11 | | -files. |
12 | | - |
13 | | -We use [Sphinx](http://www.sphinx-doc.org/) to generate the |
14 | | -documentation website, and the |
15 | | -[sphinx-js](https://pypi.python.org/pypi/sphinx-js/) extension for |
16 | | -handling the TypeDoc part. |
17 | | - |
18 | | -## How to write reStructuredText and TypeDoc |
19 | | - |
20 | | -For learning both the basics and advances features of reStructuredText, |
21 | | -we highly recommend the [reStructuredText |
22 | | -Primer](http://www.sphinx-doc.org/en/stable/rest.html) on the Sphinx |
23 | | -website. |
24 | | - |
25 | | -For TypeDoc, you can find guides as well as a detailed reference [on the |
26 | | -project\'s website](https://typedoc.org/). |
27 | | - |
28 | | -## Automatic builds and publishing |
29 | | - |
30 | | -The documentation is published via [Read the |
31 | | -Docs](https://readthedocs.org/). Whenever the Git repository\'s `master` |
32 | | -branch is pushed to GitHub, RTD will automatically build a new version |
33 | | -of the site and publish it to |
34 | | -[remotestoragejs.readthedocs.io](https://remotestoragejs.readthedocs.io). |
35 | | - |
36 | | -This means that if you want to contribute to the documentation, you |
37 | | -don\'t necessarily have to set up Sphinx and sphinx-js locally |
38 | | -(especially for small changes). However, if you want to preview what |
39 | | -your local changes look like when they are rendered as HTML, you will |
40 | | -have to set up local builds first. |
41 | | - |
42 | | -## How to build the docs on your machine |
43 | | - |
44 | | -### Setup |
45 | | - |
46 | | -1. [Install Python and PIP](https://pip.pypa.io/en/stable/installing/) |
47 | | - (likely already installed) |
| 3 | +The documentation for remoteStorage.js comes from two different sources: |
48 | 4 |
|
49 | | -2. Install sphinx-js and extensions (from repository root): |
| 5 | +1. Markdown documents in the `docs/` folder for normal pages |
| 6 | +2. TypeDoc comments in the source code, which are also rendered as Markdown pages when updating the website |
50 | 7 |
|
51 | | - ```sh |
52 | | - $ pip install -r doc/requirements.txt |
53 | | - ``` |
| 8 | +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. |
54 | 9 |
|
55 | | -3. Install TypeScript and TypeDoc globally (so Sphinx can use them): |
| 10 | +## Contributing |
56 | 11 |
|
57 | | - ```sh |
58 | | - $ npm -g install typescript typedoc |
59 | | - ``` |
| 12 | +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. |
60 | 13 |
|
61 | | -### Build |
| 14 | +## Local preview |
62 | 15 |
|
63 | | -Run the following command to automatically watch and build the |
64 | | -documentation: |
| 16 | +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: |
65 | 17 |
|
66 | 18 | ```sh |
67 | | -$ npm run autobuild-docs |
| 19 | +npm run docs:dev |
68 | 20 | ``` |
69 | 21 |
|
70 | | -This will start a web server, serving rendered HTML docs on |
71 | | -<http://localhost:8000>. |
| 22 | +If you want to edit TypeDoc comments and have the changes appear in your local preview, then you also have to run this command: |
72 | 23 |
|
73 | | -::: hint |
74 | | -::: title |
75 | | -Hint |
76 | | -::: |
77 | | - |
78 | | -The autobuild cannot watch for changes in TypeDoc comments as of now, so |
79 | | -you will need to re-run the command, or change something in a `.rst` |
80 | | -file in order for code documentation changes to be re-built. |
81 | | -::: |
82 | | - |
83 | | -## How to build the docs using ReadTheDocs\' Docker image |
84 | | - |
85 | | -This is useful for troubleshooting when the ReadTheDocs build is |
86 | | -failing. |
87 | | - |
88 | | -### Setup |
89 | | - |
90 | | -1. [Install Docker](https://docs.docker.com/get-docker/) |
91 | | - |
92 | | -2. Pull the latest version of `readthedocs/build` image with the |
93 | | - `latest` tag from Docker Hub: |
94 | | - |
95 | | - ```sh |
96 | | - $ docker pull readthedocs/build:latest |
97 | | - ``` |
98 | | - |
99 | | -### Build |
| 24 | +```sh |
| 25 | +typedoc --watch |
| 26 | +``` |
100 | 27 |
|
101 | | -1. Enter a `bash` session while attaching this project as a volume: |
| 28 | +## Publishing |
102 | 29 |
|
103 | | - ```sh |
104 | | - $ docker run --rm -it -v ${PWD}:/app readthedocs/build:latest bash |
105 | | - ``` |
| 30 | +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. |
106 | 31 |
|
107 | | -2. Run the `build-with-conda.sh` script to setup conda environment and |
108 | | - build the docs like ReadTheDocs: |
| 32 | +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. |
109 | 33 |
|
110 | | - ```sh |
111 | | - $ /app/doc/build-with-conda.sh |
112 | | - ``` |
| 34 | +> [!NOTE] |
| 35 | +> The process of updating the website automatically, whenever rs.js docs changes are merged, will be automated soon |
0 commit comments