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.

Sign up for GitHub

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

Jump to bottom

Update contributing/docs.md #1317

Merged
merged 1 commit into from
Aug 6, 2024
Merged

Update contributing/docs.md #1317

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 18 additions & 95 deletions docs/contributing/docs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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