[Doc] Add projects doc and refactor

README.md

@@ -271,7 +271,7 @@ We will keep up with the latest progress of the community, and support more popu
 
 ## Contributing
 
-We appreciate all contributions to improve MMPose. Please refer to [CONTRIBUTING.md](https://mmpose.readthedocs.io/en/1.x/notes/contribution_guide.html) for the contributing guideline.
+We appreciate all contributions to improve MMPose. Please refer to [CONTRIBUTING.md](https://mmpose.readthedocs.io/en/1.x/contribution_guide.html) for the contributing guideline.
 
 ## Acknowledgement
 

README_CN.md

@@ -268,7 +268,7 @@ mim install "mmdet>=3.0.0rc6"
 
 ## 参与贡献
 
-我们非常欢迎用户对于 MMPose 做出的任何贡献，可以参考 [贡献指南](https://mmpose.readthedocs.io/zh_CN/1.x/notes/contribution_guide.html) 文件了解更多细节。
+我们非常欢迎用户对于 MMPose 做出的任何贡献，可以参考 [贡献指南](https://mmpose.readthedocs.io/zh_CN/1.x/contribution_guide.html) 文件了解更多细节。
 
 ## 致谢
 

docs/en/collect_projects.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python
+# Copyright (c) OpenMMLab. All rights reserved.
+import os
+import os.path as osp
+import re
+from glob import glob
+
+
+def _get_project_docs():
+    """Get all project document files.
+
+    Returns:
+        list[str]: file paths
+    """
+    project_root = osp.join('..', '..', 'projects')
+    pattern = osp.sep.join(['*'] * 2) + '.md'
+    docs = glob(osp.join(project_root, pattern))
+    docs = [
+        doc for doc in docs
+        if 'example_project' not in doc and '_CN' not in doc
+    ]
+    return docs
+
+
+def _parse_project_doc_path(fn):
+    """Get project name and banner from a project reference file.
+
+    Returns:
+        tuple:
+        - project_name (str)
+        - project_banner (str)
+    """
+    project_banner, project_name = None, None
+    with open(fn, 'r', encoding='utf-8') as f:
+        for line in f.readlines():
+            if re.match('^( )*<img', line) and not project_banner:
+                project_banner = line
+            if line.startswith('# ') and not project_name:
+                project_name = line
+            if project_name and project_banner:
+                break
+    if project_name is None or project_banner is None:
+        raise ValueError(f'Invalid paper reference file {fn}')
+
+    project_name = re.sub(r'^\# ', '', project_name).strip()
+    project_banner = project_banner.strip()
+    return project_name, project_banner
+
+
+def _get_project_intro_doc():
+    project_intro_doc = []
+    with open(
+            osp.join('..', '..', 'projects', 'README.md'), 'r',
+            encoding='utf-8') as f:
+        for line in f.readlines():
+            if line.startswith('# Welcome'):
+                continue
+            if './faq.md' in line:
+                line = line.replace('./faq.md', '#faq')
+            if './' in line:
+                line = line.replace('./', '/projects/')
+            project_intro_doc.append(line)
+            if line.startswith('## Project List'):
+                break
+    return project_intro_doc
+
+
+def _get_faq_doc():
+    faq_doc = ['\n']
+    with open(
+            osp.join('..', '..', 'projects', 'faq.md'), 'r',
+            encoding='utf-8') as f:
+        for line in f.readlines():
+            if '#' in line:
+                line = re.sub(r'^\#', '##', line)
+            faq_doc.append(line)
+    return faq_doc
+
+
+def main():
+
+    # Build output folders
+    os.makedirs('projects', exist_ok=True)
+
+    # Collect all document contents
+    project_doc_list = _get_project_docs()
+
+    project_lines = []
+    for path in project_doc_list:
+        name, banner = _parse_project_doc_path(path)
+        _path = path.split(osp.sep)
+        _rel_path = _path[_path.index('projects'):-1]
+        url = '/' + '/'.join(_rel_path)
+        _name = name.split(':', 1)
+        name, description = _name[0], '' if len(
+            _name) < 2 else f': {_name[-1]}'
+        project_lines += [
+            f'- **{name}**{description} [\\[github\\]]({url})', '',
+            '<div align="center">', ' ' + banner, '</div>', '<br/>', ''
+        ]
+
+    project_intro_doc = _get_project_intro_doc()
+    faq_doc = _get_faq_doc()
+
+    with open(
+            osp.join('projects', 'community_projects.md'), 'w',
+            encoding='utf-8') as f:
+        f.write('# Projects from Community Contributors\n')
+        f.write(''.join(project_intro_doc))
+        f.write('\n'.join(project_lines))
+        f.write(''.join(faq_doc))
+
+
+if __name__ == '__main__':
+    print('collect project documents')
+    main()

docs/en/conf.py

@@ -102,6 +102,7 @@ def get_version():
 
 def builder_inited_handler(app):
     subprocess.run(['python', './collect_modelzoo.py'])
+    subprocess.run(['python', './collect_projects.py'])
     subprocess.run(['sh', './merge_docs.sh'])
     subprocess.run(['python', './stats.py'])
 

docs/en/guide_to_framework.md

@@ -1,4 +1,4 @@
-# A 20 Minute Guide to MMPose Framework
+# A 20-minute Tour to MMPose
 
 MMPose 1.0 is built upon a brand-new framework. For developers with basic knowledge of deep learning, this tutorial provides a overview of MMPose 1.0 framework design. Whether you are **a user of the previous version of MMPose**, or **a beginner of MMPose wishing to start with v1.0**, this tutorial will show you how to build a project based on MMPose 1.0.
 

docs/en/index.rst

@@ -80,6 +80,13 @@ You can change the documentation language at the lower-left corner of the page.
    dataset_zoo/3d_hand_keypoint.md
    dataset_zoo/dataset_tools.md
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Projects
+
+   projects/community_projects.md
+   projects/projects.md
+
 .. toctree::
    :maxdepth: 1
    :caption: Notes

docs/en/installation.md

@@ -1,18 +1,21 @@
 # Installation
 
+We recommend that users follow our best practices to install MMPose. However, the whole process is highly customizable. See [Customize Installation](#customize-installation) section for more information.
+
 - [Installation](#installation)
   - [Prerequisites](#prerequisites)
-  - [Install MMPose](#install-mmpose)
-    - [Best Practices](#best-practices)
-    - [Verify the installation](#verify-the-installation)
-    - [Customize Installation](#customize-installation)
-      - [CUDA versions](#cuda-versions)
-      - [Install MMEngine without MIM](#install-mmengine-without-mim)
-      - [Install MMCV without MIM](#install-mmcv-without-mim)
-      - [Install on CPU-only platforms](#install-on-cpu-only-platforms)
-      - [Install on Google Colab](#install-on-google-colab)
-      - [Using MMPose with Docker](#using-mmpose-with-docker)
-    - [Trouble shooting](#trouble-shooting)
+  - [Best Practices](#best-practices)
+    - [Build MMPose from source](#build-mmpose-from-source)
+    - [Install as a Python package](#install-as-a-python-package)
+  - [Customize Installation](#customize-installation)
+    - [CUDA versions](#cuda-versions)
+    - [Install MMEngine without MIM](#install-mmengine-without-mim)
+    - [Install MMCV without MIM](#install-mmcv-without-mim)
+    - [Install on CPU-only platforms](#install-on-cpu-only-platforms)
+    - [Install on Google Colab](#install-on-google-colab)
+    - [Using MMPose with Docker](#using-mmpose-with-docker)
+  - [Verify the installation](#verify-the-installation)
+  - [Trouble shooting](#trouble-shooting)
 
 <!-- TOC -->
 
@@ -51,13 +54,7 @@ On CPU platforms:
 conda install pytorch torchvision cpuonly -c pytorch
 ```
 
-## Install MMPose
-
-We recommend that users follow our best practices to install MMPose. However, the whole process is highly customizable. See [Customize Installation](#customize-installation) section for more information.
-
-### Best Practices
-
-**Step 0.** Install [MMEngine](https://github.com/open-mmlab/mmengine) and [MMCV](https://github.com/open-mmlab/mmcv/tree/2.x) using [MIM](https://github.com/open-mmlab/mim).
+**Step 3.** Install [MMEngine](https://github.com/open-mmlab/mmengine) and [MMCV](https://github.com/open-mmlab/mmcv/tree/2.x) using [MIM](https://github.com/open-mmlab/mim).
 
 ```shell
 pip install -U openmim
@@ -71,9 +68,11 @@ Note that some of the demo scripts in MMPose require [MMDetection](https://githu
 mim install "mmdet>=3.0.0rc6"
 ```
 
-**Step 1.** Install MMPose.
+## Best Practices
 
-Case A: To develop and run mmpose directly, install it from source:
+### Build MMPose from source
+
+To develop and run mmpose directly, install it from source:
 
 ```shell
 git clone https://github.com/open-mmlab/mmpose.git -b 1.x
@@ -86,13 +85,15 @@ pip install -v -e .
 # thus any local modifications made to the code will take effect without reinstallation.
 ```
 
-Case B: To use mmpose as a dependency or third-party package, install it with pip:
+### Install as a Python package
+
+To use mmpose as a dependency or third-party package, install it with pip:
 
 ```shell
 mim install "mmpose>=1.0.0rc1"
 ```
 
-### Verify the installation
+## Verify the installation
 
 To verify that MMPose is installed correctly, you can run an inference demo with the following steps.
 
@@ -141,9 +142,9 @@ The `demo.jpg` can be downloaded from [Github](https://raw.githubusercontent.com
 
 The inference results will be a list of `PoseDataSample`, and the predictions are in the `pred_instances`, indicating the detected keypoint locations and scores.
 
-### Customize Installation
+## Customize Installation
 
-#### CUDA versions
+### CUDA versions
 
 When installing PyTorch, you need to specify the version of CUDA. If you are not clear on which to choose, follow our recommendations:
 
@@ -154,7 +155,7 @@ Please make sure the GPU driver satisfies the minimum version requirements. See
 
 Installing CUDA runtime libraries is enough if you follow our best practices, because no CUDA code will be compiled locally. However if you hope to compile MMCV from source or develop other CUDA operators, you need to install the complete CUDA toolkit from NVIDIA's [website](https://developer.nvidia.com/cuda-downloads), and its version should match the CUDA version of PyTorch. i.e., the specified version of cudatoolkit in `conda install` command.
 
-#### Install MMEngine without MIM
+### Install MMEngine without MIM
 
 To install MMEngine with pip instead of MIM, please follow [MMEngine installation guides](https://mmengine.readthedocs.io/zh_CN/latest/get_started/installation.html).
 
@@ -164,7 +165,7 @@ For example, you can install MMEngine by the following command.
 pip install mmengine
 ```
 
-#### Install MMCV without MIM
+### Install MMCV without MIM
 
 MMCV contains C++ and CUDA extensions, thus depending on PyTorch in a complex way. MIM solves such dependencies automatically and makes the installation easier. However, it is not a must.
 
@@ -176,13 +177,13 @@ For example, the following command install mmcv built for PyTorch 1.10.x and CUD
 pip install 'mmcv>=2.0.0rc1' -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10/index.html
 ```
 
-#### Install on CPU-only platforms
+### Install on CPU-only platforms
 
 MMPose can be built for CPU only environment. In CPU mode you can train, test or inference a model.
 
 However, some functionalities are missing in this mode, usually GPU-compiled ops like `Deformable Convolution`. Most models in MMPose don't depend on these ops, but if you try to train/test/infer a model containing these ops, an error will be raised.
 
-#### Install on Google Colab
+### Install on Google Colab
 
 [Google Colab](https://colab.research.google.com/) usually has PyTorch installed,
 thus we only need to install MMEngine, MMCV and MMPose with the following commands.
@@ -215,7 +216,7 @@ print(mmpose.__version__)
 Note that within Jupyter, the exclamation mark `!` is used to call external executables and `%cd` is a [magic command](https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-cd) to change the current working directory of Python.
 ```
 
-#### Using MMPose with Docker
+### Using MMPose with Docker
 
 We provide a [Dockerfile](https://github.com/open-mmlab/mmpose/blob/master/docker/Dockerfile) to build an image. Ensure that your [docker version](https://docs.docker.com/engine/install/) >=19.03.
 
@@ -239,7 +240,7 @@ docker run --gpus all --shm-size=8g -it -v {DATA_DIR}:/mmpose/data mmpose
 If you encounter the error message like `permission denied`, please add `sudo` at the start of the command and try it again.
 ```
 
-### Trouble shooting
+## Trouble shooting
 
-If you have some issues during the installation, please first view the [FAQ](./notes/faq.md) page.
+If you have some issues during the installation, please first view the [FAQ](./faq.md) page.
 You may [open an issue](https://github.com/open-mmlab/mmpose/issues/new/choose) on GitHub if no solution is found.

docs/en/merge_docs.sh

@@ -2,7 +2,7 @@
 # Copyright (c) OpenMMLab. All rights reserved.
 
 sed -i '$a\\n' ../../demo/docs/*_demo.md
-cat ../../demo/docs/*_demo.md | sed "s/#/#&/" | sed "s/md###t/html#t/g" | sed '1i\# Demo' | sed 's=](/docs/en/=](/=g' | sed 's=](/=](https://github.com/open-mmlab/mmpose/tree/1.x/=g' >demo.md
+cat ../../demo/docs/*_demo.md | sed "s/^## 2D\(.*\)Demo/##\1Estimation/" | sed "s/md###t/html#t/g" | sed '1i\# Demos\n' | sed 's=](/docs/en/=](/=g' | sed 's=](/=](https://github.com/open-mmlab/mmpose/tree/1.x/=g' >demos.md
 
  # remove /docs/ for link used in doc site
 sed -i 's=](/docs/en/=](=g' overview.md
@@ -15,6 +15,7 @@ sed -i 's=](/docs/en/=](=g' ./user_guides/*.md
 sed -i 's=](/docs/en/=](=g' ./advanced_guides/*.md
 sed -i 's=](/docs/en/=](=g' ./dataset_zoo/*.md
 sed -i 's=](/docs/en/=](=g' ./notes/*.md
+sed -i 's=](/docs/en/=](=g' ./projects/*.md
 
 
 sed -i 's=](/=](https://github.com/open-mmlab/mmpose/tree/1.x/=g' overview.md
@@ -27,3 +28,4 @@ sed -i 's=](/=](https://github.com/open-mmlab/mmpose/tree/1.x/=g' ./model_zoo_pa
 sed -i 's=](/=](https://github.com/open-mmlab/mmpose/tree/1.x/=g' ./user_guides/*.md
 sed -i 's=](/=](https://github.com/open-mmlab/mmpose/tree/1.x/=g' ./dataset_zoo/*.md
 sed -i 's=](/=](https://github.com/open-mmlab/mmpose/tree/1.x/=g' ./notes/*.md
+sed -i 's=](/=](https://github.com/open-mmlab/mmpose/tree/1.x/=g' ./projects/*.md

docs/en/overview.md

@@ -46,6 +46,6 @@ We have prepared detailed guidelines for all types of users:
 4. For developers who wish to develop based on MMPose:
    - [Migration Guide](./migration.md)
 5. For researchers and developers who are willing to contribute to MMPose:
-   - [Contribution Guide](./notes/contribution_guide.md)
+   - [Contribution Guide](./contribution_guide.md)
 6. For some common issues, we provide a FAQ list:
-   - [FAQ](./notes/faq.md)
+   - [FAQ](./faq.md)