142 lines
4.1 KiB
Markdown
142 lines
4.1 KiB
Markdown
|
## Basic manual
|
|||
|
|
|
|||
|
|
### How to edit or add documentation pages online
|
|||
|
|
|
|||
|
|
To edit and/or add documentation, you need to have a [GitHub](https://github.com/login) account.
|
|||
|
|
To change documentation files or add a documentation page,
|
|||
|
|
simply click `Edit this page` on the page you would like to edit.
|
|||
|
|
If you need to add a child page, click `Create child page`.
|
|||
|
|
|
|||
|
|
If you need to edit the text that has the markup [markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet),
|
|||
|
|
click on the `Fork this repository` button.
|
|||
|
|
|
|||
|
|
Read how to edit files for github ([GitHub docs](https://docs.github.com/en/github/managing-files-in-a-repository/editing-files-in-another-users-repository)).
|
|||
|
|
|
|||
|
|
Please note that files have a markup for correct display on the site: the title, the title of the link,
|
|||
|
|
the weight (affects the order of files displayed on the sidebar) and description (optional):
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
---
|
|||
|
|
title: "Title"
|
|||
|
|
linkTitle: "Link Title"
|
|||
|
|
weight: 1
|
|||
|
|
description: >
|
|||
|
|
Description
|
|||
|
|
---
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
|
|||
|
|
### How to start the site locally
|
|||
|
|
|
|||
|
|
#### Installation
|
|||
|
|
|
|||
|
|
1. Install Hugo
|
|||
|
|
|
|||
|
|
Get the [v110.0-extended release of hugo](https://github.com/gohugoio/hugo/releases/tag/v0.110.0).
|
|||
|
|
Expand the Assets section of the release on GitHub and scroll down
|
|||
|
|
until you find a list of **Extended** versions.
|
|||
|
|
[Read more](https://gohugo.io/getting-started/installing/#quick-install)
|
|||
|
|
|
|||
|
|
Add a path to `hugo` in the `PATH` environment variable.
|
|||
|
|
|
|||
|
|
2. Get the Docsy theme code
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
git submodule update --init --recursive
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
3. Install the Docsy theme dependencies
|
|||
|
|
|
|||
|
|
To build or update your site’s CSS resources, you will need several packages installed.
|
|||
|
|
To install them, you must have a recent version of [NodeJS](https://nodejs.org/en/)
|
|||
|
|
installed on your machine (tested with v18.0). For this, you can use
|
|||
|
|
[npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) directly
|
|||
|
|
or via an environment manager like [nvm](https://github.com/nvm-sh/nvm).
|
|||
|
|
By default `npm` installs tools under the directory where you run `npm install`.
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
(cd site/ && npm ci)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
The full documentation is available
|
|||
|
|
[here](https://www.docsy.dev/docs/get-started/other-options/#for-an-existing-site).
|
|||
|
|
|
|||
|
|
4. To preview your site locally, use:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
(cd site/ && hugo server)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
By default, your site will be available at <http://localhost:1313/docs/>.
|
|||
|
|
|
|||
|
|
#### How to build for production deployment
|
|||
|
|
|
|||
|
|
1. Install dependencies
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
cd site/
|
|||
|
|
pip -m venv venv
|
|||
|
|
. venv/bin/activate
|
|||
|
|
pip install -r requirements.txt
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
The documentation site includes the last MAX_VERSIONS_TO_BUILD releases
|
|||
|
|
(they are defined in `build_docs.py`). To build the website, you only need:
|
|||
|
|
- `hugo-0.110` - for all documentation builds
|
|||
|
|
|
|||
|
|
Please download this hugo release (extended), and make the binary
|
|||
|
|
available in your `PATH` environment variable.
|
|||
|
|
|
|||
|
|
On Linux, you can install it this way:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
wget https://github.com/gohugoio/hugo/releases/download/v0.110.0/hugo_extended_0.110.0_Linux-64bit.tar.gz
|
|||
|
|
(mkdir hugo_extended_0.110.0_Linux-64bit && tar -xf hugo_extended_0.110.0_Linux-64bit.tar.gz -C hugo_extended_0.110.0_Linux-64bit)
|
|||
|
|
cd hugo_extended_0.110.0_Linux-64bit
|
|||
|
|
sudo cp hugo /usr/local/bin/hugo-0.110
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
2. Use the commands that generate a static site in the `public/` folder:
|
|||
|
|
|
|||
|
|
Make sure to generate the SDK code first.
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
python process_sdk_docs.py --input-dir ../cvat-sdk/docs/ --site-root .
|
|||
|
|
|
|||
|
|
python build_docs.py
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
The resulting folder contains the whole site, which can be published by a server like Apache.
|
|||
|
|
Read more [here](https://www.docsy.dev/docs/getting-started/)
|
|||
|
|
and [here](https://gohugo.io/hosting-and-deployment/).
|
|||
|
|
|
|||
|
|
You can also deploy the website locally:
|
|||
|
|
```bash
|
|||
|
|
python -m http.server -d path/to/public
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### How to update the submodule of the Docsy theme
|
|||
|
|
|
|||
|
|
To update the submodule of the docsy theme, you need to have a repository clone.
|
|||
|
|
While in the repository folder, use the git command:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
git submodule update --remote
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Add and then commit the change to project:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
git add themes/
|
|||
|
|
git commit -m "Updating theme submodule"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Push the commit to project repo. For example, run:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
git push
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Make sure to update the corresponding configuration files and
|
|||
|
|
theme overrides (`layouts/`, `i18n/`, etc.).
|