From cc43006aa3abe47db091891e642825b87df06892 Mon Sep 17 00:00:00 2001 From: Chuanbo Hua Date: Thu, 13 Jul 2023 03:21:12 +0900 Subject: [PATCH 1/2] [Document] update README for docs --- docs/README.md | 89 +++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 70 insertions(+), 19 deletions(-) diff --git a/docs/README.md b/docs/README.md index 9dc46923..3bdcb189 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,7 @@ -# RL4CO Docs +# 📑 RL4CO Docs -We are using Sphinx with Napoleon extension. -Moreover, we set Google style to follow with type convention. +We are using [Sphinx](https://www.sphinx-doc.org/en/master/) with [Napoleon extension](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html) to build the documentation. +Moreover, we set [Google style](https://google.github.io/styleguide/pyguide.html) to follow with type convention. - [Napoleon formatting with Google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) - [ReStructured Text (reST)](https://docs.pylonsproject.org/projects/docs-style-guide/) @@ -35,29 +35,80 @@ def my_func(param_a: int, param_b: Optional[float] = None) -> str: return str(param_a + p) ``` -## Building Docs +## 🗂️ File structures -When updating the docs, make sure to build them first locally and visually inspect the html files in your browser for -formatting errors. In certain cases, a missing blank line or a wrong indent can lead to a broken layout. -Run these commands - -```bash -git submodule update --init --recursive -make docs ``` +. +├── _build/ - output website, only for local building +├── _content/ - content for docs pages in Markdown format +├── _theme/ +│ └── rl4co/ - website theme files +├── conf.py - main config file for building +├── index.md - content for index page +├── make.bat - building script for Windows +├── Makefile - building script for Unix +├── README.md +└── requirements.txt - requirement python packages for Read the Docs building +``` + +## ⚙️ Build docs locally + +**Step 1**. Install requirement packages: `pip install -r requirement.txt`; + +**Step 2**. Run the building script: + +- **Windows**: run `make.bat`; +- **Linux/macOS**: run `make html`; + +The generated docs will be under the `_build` folder. You can open `docs/build/html/index.html` in your browser to check the docs. + +We need to have LaTeX installed for rendering math equations. You can for example install TeXLive with the necessary extras by doing one of the following: -and open `docs/build/html/index.html` in your browser. +- **Windows/macOS**: check the [Tex Live install guide](https://www.tug.org/texlive/windows.html) for Windows/macOS; +- **Ubuntu (Linux)**: run `sudo apt-get update && sudo apt-get install -y texlive-latex-extra dvipng texlive-pictures`; +- Use the [RTD docker image](https://hub.docker.com/r/readthedocs/build); -When you send a PR the continuous integration will run tests and build the docs. +## ⚙️ Build in Read the Docs -Notes: +In the root of this repository, there is `.readthedocs.yaml` which will be loaded by the Read the Docs to build the docs. Please refer to the [configuration file v2 guide from Read the Docs](https://docs.readthedocs.io/en/stable/config-file/v2.html) for details information of variables. -- You need to have LaTeX installed for rendering math equations. You can for example install TeXLive with the necessary extras by doing one of the following: - - on Ubuntu (Linux) run `sudo apt-get update && sudo apt-get install -y texlive-latex-extra dvipng texlive-pictures` - - use the [RTD docker image](https://hub.docker.com/r/readthedocs/build) -- You need to have pandoc installed for rendering Jupyter Notebooks. On Ubuntu (Linux), you can run: `sudo apt-get install pandoc` +## 💡 Notes for contents +
+Markdown and RST support +RST is originally supported by the Sphinx. With the extension `myst_parser` it can support Markdown contents. Follow [this guide](https://www.sphinx-doc.org/en/master/usage/markdown.html) to learn more. +In the meantime, we can still use RST within Markdown files by +```` +```{eval-rst} +RST CONTENTS +``` +```` +
+
+Jupyter notebook support +With the extension `nbsphinx`, Sphinx can support Jupyter notebook. Follow [this guide](https://docs.readthedocs.io/en/stable/guides/jupyter.html) to learn more. + +Indexing a Jupyter notebook is the same with a Markdown file in RST: +``` +.. toctree:: + :maxdepth: 2 + :caption: Getting started: + + _content/start/installation + _content/start/quickstart_notebook +``` +
+
+API docs auto generator +With Sphinx's `automodule` we can easily get the API docs: +``` +.. automodule:: rl4co.data.generate_data + :members: + :undoc-members: +``` +When deploy in Read the Docs, make sure putting the package to `requirement.txt` mentioned before. +
-## References +## 📚 References We base the above guide on the official [PyTorch Lightning Docs](https://github.com/Lightning-AI/lightning/tree/master/docs). \ No newline at end of file From 5de9a04354e14441bed8ae43e2aee6b40f813ea6 Mon Sep 17 00:00:00 2001 From: Chuanbo HUA Date: Fri, 21 Jul 2023 16:36:35 +0900 Subject: [PATCH 2/2] [Docs] update rl4co title bar image --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index a39d3b4b..a73d01e6 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,6 @@
-# RL4CO - +![rl4co_titlebar_withlogo](https://github.com/kaist-silab/rl4co/assets/34462374/58e087eb-8791-4e92-a9da-fe0f680a11e4) PyTorch Lightning