From 45b63c584f79ae69168d72f2e0fb805f47ec66e5 Mon Sep 17 00:00:00 2001
From: Miao Zheng <76149310+MeowZheng@users.noreply.github.com>
Date: Wed, 17 Aug 2022 10:59:38 +0800
Subject: [PATCH] [Doc] MMSeg 1.x Documentation (#1924)

* [Doc] MMSeg 1.x Documentation

* revise index
---
 .../add_dataset.md}                           |  0
 .../add_modules.md}                           |  0
 .../customize_runtime.md                      |  0
 docs/en/advanced_guides/data_flow.md          |  1 +
 docs/en/advanced_guides/datasets.md           |  1 +
 docs/en/advanced_guides/engine.md             |  1 +
 docs/en/advanced_guides/evaluation.md         |  1 +
 docs/en/advanced_guides/index.rst             | 26 ++++++++++
 docs/en/advanced_guides/models.md             |  1 +
 docs/en/advanced_guides/structures.md         |  1 +
 .../training_tricks.md                        |  0
 .../transforms.md}                            |  0
 docs/en/index.rst                             | 51 +++++++++----------
 docs/en/migration.md                          |  1 +
 docs/en/{ => notes}/changelog.md              |  0
 docs/en/{ => notes}/faq.md                    |  0
 docs/en/tutorials/index.rst                   |  9 ----
 .../config.md => user_guides/1_config.md}     |  0
 .../2_dataset_prepare.md}                     |  0
 .../3_inference.md}                           |  0
 .../{train.md => user_guides/4_train_test.md} |  0
 docs/en/user_guides/index.rst                 | 19 +++++++
 docs/en/{ => user_guides}/useful_tools.md     |  0
 docs/en/user_guides/visualization.md          |  1 +
 requirements/docs.txt                         |  2 +-
 25 files changed, 77 insertions(+), 38 deletions(-)
 rename docs/en/{tutorials/customize_datasets.md => advanced_guides/add_dataset.md} (100%)
 rename docs/en/{tutorials/customize_models.md => advanced_guides/add_modules.md} (100%)
 rename docs/en/{tutorials => advanced_guides}/customize_runtime.md (100%)
 create mode 100644 docs/en/advanced_guides/data_flow.md
 create mode 100644 docs/en/advanced_guides/datasets.md
 create mode 100644 docs/en/advanced_guides/engine.md
 create mode 100644 docs/en/advanced_guides/evaluation.md
 create mode 100644 docs/en/advanced_guides/index.rst
 create mode 100644 docs/en/advanced_guides/models.md
 create mode 100644 docs/en/advanced_guides/structures.md
 rename docs/en/{tutorials => advanced_guides}/training_tricks.md (100%)
 rename docs/en/{tutorials/data_pipeline.md => advanced_guides/transforms.md} (100%)
 create mode 100644 docs/en/migration.md
 rename docs/en/{ => notes}/changelog.md (100%)
 rename docs/en/{ => notes}/faq.md (100%)
 delete mode 100644 docs/en/tutorials/index.rst
 rename docs/en/{tutorials/config.md => user_guides/1_config.md} (100%)
 rename docs/en/{dataset_prepare.md => user_guides/2_dataset_prepare.md} (100%)
 rename docs/en/{inference.md => user_guides/3_inference.md} (100%)
 rename docs/en/{train.md => user_guides/4_train_test.md} (100%)
 create mode 100644 docs/en/user_guides/index.rst
 rename docs/en/{ => user_guides}/useful_tools.md (100%)
 create mode 100644 docs/en/user_guides/visualization.md

diff --git a/docs/en/tutorials/customize_datasets.md b/docs/en/advanced_guides/add_dataset.md
similarity index 100%
rename from docs/en/tutorials/customize_datasets.md
rename to docs/en/advanced_guides/add_dataset.md
diff --git a/docs/en/tutorials/customize_models.md b/docs/en/advanced_guides/add_modules.md
similarity index 100%
rename from docs/en/tutorials/customize_models.md
rename to docs/en/advanced_guides/add_modules.md
diff --git a/docs/en/tutorials/customize_runtime.md b/docs/en/advanced_guides/customize_runtime.md
similarity index 100%
rename from docs/en/tutorials/customize_runtime.md
rename to docs/en/advanced_guides/customize_runtime.md
diff --git a/docs/en/advanced_guides/data_flow.md b/docs/en/advanced_guides/data_flow.md
new file mode 100644
index 000000000..59e7ca329
--- /dev/null
+++ b/docs/en/advanced_guides/data_flow.md
@@ -0,0 +1 @@
+# Data Flow
diff --git a/docs/en/advanced_guides/datasets.md b/docs/en/advanced_guides/datasets.md
new file mode 100644
index 000000000..157ea3aad
--- /dev/null
+++ b/docs/en/advanced_guides/datasets.md
@@ -0,0 +1 @@
+# Datasets
diff --git a/docs/en/advanced_guides/engine.md b/docs/en/advanced_guides/engine.md
new file mode 100644
index 000000000..eaa55b0c8
--- /dev/null
+++ b/docs/en/advanced_guides/engine.md
@@ -0,0 +1 @@
+# Engine
diff --git a/docs/en/advanced_guides/evaluation.md b/docs/en/advanced_guides/evaluation.md
new file mode 100644
index 000000000..b394c7690
--- /dev/null
+++ b/docs/en/advanced_guides/evaluation.md
@@ -0,0 +1 @@
+# Evaluation
diff --git a/docs/en/advanced_guides/index.rst b/docs/en/advanced_guides/index.rst
new file mode 100644
index 000000000..1cae420c1
--- /dev/null
+++ b/docs/en/advanced_guides/index.rst
@@ -0,0 +1,26 @@
+Basic Concepts
+***************
+
+.. toctree::
+   :maxdepth: 1
+
+   data_flow.md
+   structures.md
+   models.md
+   datasets.md
+   transforms.md
+   evaluation.md
+   engine.md
+   training_tricks.md
+
+Component Customization
+************************
+
+.. toctree::
+   :maxdepth: 1
+
+   add_modules.md
+   add_datasets.md
+   add_transforms.md
+   add_metrics.md
+   customize_runtime.md
diff --git a/docs/en/advanced_guides/models.md b/docs/en/advanced_guides/models.md
new file mode 100644
index 000000000..91361720e
--- /dev/null
+++ b/docs/en/advanced_guides/models.md
@@ -0,0 +1 @@
+# Models
diff --git a/docs/en/advanced_guides/structures.md b/docs/en/advanced_guides/structures.md
new file mode 100644
index 000000000..985286177
--- /dev/null
+++ b/docs/en/advanced_guides/structures.md
@@ -0,0 +1 @@
+# Structures
diff --git a/docs/en/tutorials/training_tricks.md b/docs/en/advanced_guides/training_tricks.md
similarity index 100%
rename from docs/en/tutorials/training_tricks.md
rename to docs/en/advanced_guides/training_tricks.md
diff --git a/docs/en/tutorials/data_pipeline.md b/docs/en/advanced_guides/transforms.md
similarity index 100%
rename from docs/en/tutorials/data_pipeline.md
rename to docs/en/advanced_guides/transforms.md
diff --git a/docs/en/index.rst b/docs/en/index.rst
index ae009bf44..2668bc1f3 100644
--- a/docs/en/index.rst
+++ b/docs/en/index.rst
@@ -1,17 +1,34 @@
 Welcome to MMSegmentation's documentation!
-=======================================
+===========================================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Get Started
 
    get_started.md
 
 .. toctree::
-   :maxdepth: 1
-   :caption: Dataset Preparation
+   :maxdepth: 2
+   :caption: User Guides
 
-   dataset_prepare.md
+   user_guides/index.rst
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Advanced Guides
+
+   advanced_guides/index.rst
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Migration
+
+   migration.md
+
+.. toctree::
+   :caption: API Reference
+
+   api.rst
 
 .. toctree::
    :maxdepth: 1
@@ -21,26 +38,7 @@ Welcome to MMSegmentation's documentation!
    modelzoo_statistics.md
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Quick Run
-
-   train.md
-   inference.md
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Tutorials
-
-   tutorials/index.rst
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Useful Tools and Scripts
-
-   useful_tools.md
-
-.. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Notes
 
    changelog.md
@@ -51,10 +49,7 @@ Welcome to MMSegmentation's documentation!
 
    switch_language.md
 
-.. toctree::
-   :caption: API Reference
 
-   api.rst
 
 Indices and tables
 ==================
diff --git a/docs/en/migration.md b/docs/en/migration.md
new file mode 100644
index 000000000..ac49e6768
--- /dev/null
+++ b/docs/en/migration.md
@@ -0,0 +1 @@
+# Migration from MMSegmentation 0.x
diff --git a/docs/en/changelog.md b/docs/en/notes/changelog.md
similarity index 100%
rename from docs/en/changelog.md
rename to docs/en/notes/changelog.md
diff --git a/docs/en/faq.md b/docs/en/notes/faq.md
similarity index 100%
rename from docs/en/faq.md
rename to docs/en/notes/faq.md
diff --git a/docs/en/tutorials/index.rst b/docs/en/tutorials/index.rst
deleted file mode 100644
index e1a67a8b4..000000000
--- a/docs/en/tutorials/index.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-.. toctree::
-   :maxdepth: 2
-
-   config.md
-   customize_datasets.md
-   data_pipeline.md
-   customize_models.md
-   training_tricks.md
-   customize_runtime.md
diff --git a/docs/en/tutorials/config.md b/docs/en/user_guides/1_config.md
similarity index 100%
rename from docs/en/tutorials/config.md
rename to docs/en/user_guides/1_config.md
diff --git a/docs/en/dataset_prepare.md b/docs/en/user_guides/2_dataset_prepare.md
similarity index 100%
rename from docs/en/dataset_prepare.md
rename to docs/en/user_guides/2_dataset_prepare.md
diff --git a/docs/en/inference.md b/docs/en/user_guides/3_inference.md
similarity index 100%
rename from docs/en/inference.md
rename to docs/en/user_guides/3_inference.md
diff --git a/docs/en/train.md b/docs/en/user_guides/4_train_test.md
similarity index 100%
rename from docs/en/train.md
rename to docs/en/user_guides/4_train_test.md
diff --git a/docs/en/user_guides/index.rst b/docs/en/user_guides/index.rst
new file mode 100644
index 000000000..d10989744
--- /dev/null
+++ b/docs/en/user_guides/index.rst
@@ -0,0 +1,19 @@
+Train & Test
+**************
+
+.. toctree::
+   :maxdepth: 1
+
+   1_config.md
+   2_dataset_prepare.md
+   3_inference.md
+   4_train_test.md
+
+Useful Tools
+*************
+
+.. toctree::
+   :maxdepth: 2
+
+   useful_tools.md
+   visualization.md
diff --git a/docs/en/useful_tools.md b/docs/en/user_guides/useful_tools.md
similarity index 100%
rename from docs/en/useful_tools.md
rename to docs/en/user_guides/useful_tools.md
diff --git a/docs/en/user_guides/visualization.md b/docs/en/user_guides/visualization.md
new file mode 100644
index 000000000..f0fa8b814
--- /dev/null
+++ b/docs/en/user_guides/visualization.md
@@ -0,0 +1 @@
+# Visualization
diff --git a/requirements/docs.txt b/requirements/docs.txt
index 20170845c..8e98c16fc 100644
--- a/requirements/docs.txt
+++ b/requirements/docs.txt
@@ -1,6 +1,6 @@
 docutils==0.16.0
 myst-parser
--e git+https://github.com/gaotongxiao/pytorch_sphinx_theme.git#egg=pytorch_sphinx_theme
+-e git+https://github.com/open-mmlab/pytorch_sphinx_theme.git#egg=pytorch_sphinx_theme
 sphinx==4.0.2
 sphinx_copybutton
 sphinx_markdown_tables