diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..718eddc --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# Copyright (c) Facebook, Inc. and its affiliates. + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..ba8607e --- /dev/null +++ b/docs/README.md @@ -0,0 +1,16 @@ +# Read the docs: + +The latest documentation built from this directory is available at [detectron2.readthedocs.io](https://detectron2.readthedocs.io/). +Documents in this directory are not meant to be read on github. + +# Build the docs: + +1. Install detectron2 according to [INSTALL.md](https://github.com/facebookresearch/detectron2/blob/master/INSTALL.md). +2. Install additional libraries required to build docs: + - docutils==0.16 + - Sphinx==3.0.0 + - recommonmark==0.6.0 + - sphinx_rtd_theme + - mock + +3. Run `make html` from this directory. diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 0000000..a272c68 --- /dev/null +++ b/docs/_static/css/custom.css @@ -0,0 +1,25 @@ +/* + * Copyright (c) Facebook, Inc. and its affiliates. + * some extra css to make markdown look similar between github/sphinx + */ + +/* + * Below is for install.md: + */ +.rst-content code { + white-space: pre; + border: 0px; +} + +.rst-content th { + border: 1px solid #e1e4e5; +} + +.rst-content th p { + /* otherwise will be default 24px for regular paragraph */ + margin-bottom: 0px; +} + +div.section > details { + padding-bottom: 1em; +} diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..aad5c16 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,356 @@ +# -*- coding: utf-8 -*- +# Copyright (c) Facebook, Inc. and its affiliates. + +# flake8: noqa + +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +from unittest import mock +from sphinx.domains import Domain +from typing import Dict, List, Tuple + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +import sphinx_rtd_theme + + +class GithubURLDomain(Domain): + """ + Resolve certain links in markdown files to github source. + """ + + name = "githuburl" + ROOT = "https://github.com/JDAI-CV/fast-reid/tree/master" + LINKED_DOC = ["tutorials/install", "tutorials/getting_started"] + + def resolve_any_xref(self, env, fromdocname, builder, target, node, contnode): + github_url = None + if not target.endswith("html") and target.startswith("../../"): + url = target.replace("../", "") + github_url = url + if fromdocname in self.LINKED_DOC: + # unresolved links in these docs are all github links + github_url = target + + if github_url is not None: + if github_url.endswith("MODEL_ZOO") or github_url.endswith("README"): + # bug of recommonmark. + # https://github.com/readthedocs/recommonmark/blob/ddd56e7717e9745f11300059e4268e204138a6b1/recommonmark/parser.py#L152-L155 + github_url += ".md" + print("Ref {} resolved to github:{}".format(target, github_url)) + contnode["refuri"] = self.ROOT + github_url + return [("githuburl:any", contnode)] + else: + return [] + + +# to support markdown +from recommonmark.parser import CommonMarkParser + +sys.path.insert(0, os.path.abspath("../")) +os.environ["DOC_BUILDING"] = "True" +DEPLOY = os.environ.get("READTHEDOCS") == "True" + + +# -- Project information ----------------------------------------------------- + +# fmt: off +try: + import torch # noqa +except ImportError: + for m in [ + "torch", "torchvision", "torch.nn", "torch.nn.parallel", "torch.distributed", "torch.multiprocessing", "torch.autograd", + "torch.autograd.function", "torch.nn.modules", "torch.nn.modules.utils", "torch.utils", "torch.utils.data", "torch.onnx", + "torchvision", "torchvision.ops", + ]: + sys.modules[m] = mock.Mock(name=m) + sys.modules['torch'].__version__ = "1.5" # fake version + +for m in [ + "cv2", "scipy", "portalocker", + "google", "google.protobuf", "google.protobuf.internal", "onnx", +]: + sys.modules[m] = mock.Mock(name=m) +# fmt: on +sys.modules["cv2"].__version__ = "3.4" + +import fastreid # isort: skip + + +project = "fastreid" +copyright = "2019-2020, fastreid contributors" +author = "fastreid contributors" + +# The short X.Y version +version = fastreid.__version__ +# The full version, including alpha/beta/rc tags +release = version + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +needs_sphinx = "3.0" + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "recommonmark", + "sphinx.ext.autodoc", + "sphinx.ext.napoleon", + "sphinx.ext.intersphinx", + "sphinx.ext.todo", + "sphinx.ext.coverage", + "sphinx.ext.mathjax", + "sphinx.ext.viewcode", + "sphinx.ext.githubpages", +] + +# -- Configurations for plugins ------------ +napoleon_google_docstring = True +napoleon_include_init_with_doc = True +napoleon_include_special_with_doc = True +napoleon_numpy_docstring = False +napoleon_use_rtype = False +autodoc_inherit_docstrings = False +autodoc_member_order = "bysource" + +if DEPLOY: + intersphinx_timeout = 10 +else: + # skip this when building locally + intersphinx_timeout = 0.1 +intersphinx_mapping = { + "python": ("https://docs.python.org/3.6", None), + "numpy": ("https://docs.scipy.org/doc/numpy/", None), + "torch": ("https://pytorch.org/docs/master/", None), +} +# ------------------------- + + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +source_suffix = [".rst", ".md"] + +# The master toctree document. +master_doc = "index" + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "build", "README.md", "tutorials/README.md"] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = "sphinx" + + +# -- Options for HTML output ------------------------------------------------- + +html_theme = "sphinx_rtd_theme" +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] +html_css_files = ["css/custom.css"] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = "fastreiddoc" + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, "fastreid.tex", "fastreid Documentation", "fastreid contributors", "manual") +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [(master_doc, "fastreid", "fastreid Documentation", [author], 1)] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ( + master_doc, + "fastreid", + "fastreid Documentation", + author, + "fastreid", + "One line description of project.", + "Miscellaneous", + ) +] + + +# -- Options for todo extension ---------------------------------------------- + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +def autodoc_skip_member(app, what, name, obj, skip, options): + # we hide something deliberately + if getattr(obj, "__HIDE_SPHINX_DOC__", False): + return True + + # Hide some that are deprecated or not intended to be used + HIDDEN = { + # "ResNetBlockBase", + "GroupedBatchSampler", + # "build_transform_gen", + # "export_caffe2_model", + # "export_onnx_model", + # "apply_transform_gens", + # "TransformGen", + # "apply_augmentations", + # "StandardAugInput", + # "build_batch_data_loader", + # "draw_panoptic_seg_predictions", + } + try: + if name in HIDDEN or ( + hasattr(obj, "__doc__") and obj.__doc__.lower().strip().startswith("deprecated") + ): + print("Skipping deprecated object: {}".format(name)) + return True + except: + pass + return skip + + +_PAPER_DATA = { + "resnet": ("1512.03385", "Deep Residual Learning for Image Recognition"), + "fpn": ("1612.03144", "Feature Pyramid Networks for Object Detection"), + "mask r-cnn": ("1703.06870", "Mask R-CNN"), + "faster r-cnn": ( + "1506.01497", + "Faster R-CNN: Towards Real-Time Object Detection with Region Proposal Networks", + ), + "deformconv": ("1703.06211", "Deformable Convolutional Networks"), + "deformconv2": ("1811.11168", "Deformable ConvNets v2: More Deformable, Better Results"), + "panopticfpn": ("1901.02446", "Panoptic Feature Pyramid Networks"), + "retinanet": ("1708.02002", "Focal Loss for Dense Object Detection"), + "cascade r-cnn": ("1712.00726", "Cascade R-CNN: Delving into High Quality Object Detection"), + "lvis": ("1908.03195", "LVIS: A Dataset for Large Vocabulary Instance Segmentation"), + "rrpn": ("1703.01086", "Arbitrary-Oriented Scene Text Detection via Rotation Proposals"), + "imagenet in 1h": ("1706.02677", "Accurate, Large Minibatch SGD: Training ImageNet in 1 Hour"), + "xception": ("1610.02357", "Xception: Deep Learning with Depthwise Separable Convolutions"), + "mobilenet": ( + "1704.04861", + "MobileNets: Efficient Convolutional Neural Networks for Mobile Vision Applications", + ), +} + + +def paper_ref_role( + typ: str, + rawtext: str, + text: str, + lineno: int, + inliner, + options: Dict = {}, + content: List[str] = [], +): + """ + Parse :paper:`xxx`. Similar to the "extlinks" sphinx extension. + """ + from docutils import nodes, utils + from sphinx.util.nodes import split_explicit_title + + text = utils.unescape(text) + has_explicit_title, title, link = split_explicit_title(text) + link = link.lower() + if link not in _PAPER_DATA: + inliner.reporter.warning("Cannot find paper " + link) + paper_url, paper_title = "#", link + else: + paper_url, paper_title = _PAPER_DATA[link] + if "/" not in paper_url: + paper_url = "https://arxiv.org/abs/" + paper_url + if not has_explicit_title: + title = paper_title + pnode = nodes.reference(title, title, internal=False, refuri=paper_url) + return [pnode], [] + + +def setup(app): + from recommonmark.transform import AutoStructify + + app.add_domain(GithubURLDomain) + app.connect("autodoc-skip-member", autodoc_skip_member) + app.add_role("paper", paper_ref_role) + app.add_config_value( + "recommonmark_config", + {"enable_math": True, "enable_inline_math": True, "enable_eval_rst": True}, + True, + ) + app.add_transform(AutoStructify) diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..8634b7b --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,14 @@ +.. detectron2 documentation master file, created by + sphinx-quickstart on Sat Sep 21 13:46:45 2019. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to detectron2's documentation! +====================================== + +.. toctree:: + :maxdepth: 2 + + tutorials/index + notes/index + modules/index diff --git a/docs/modules/checkpoint.rst b/docs/modules/checkpoint.rst new file mode 100644 index 0000000..0dde84f --- /dev/null +++ b/docs/modules/checkpoint.rst @@ -0,0 +1,7 @@ +fastreid.checkpoint +============================= + +.. automodule:: fastreid.utils.checkpoint + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/modules/config.rst b/docs/modules/config.rst new file mode 100644 index 0000000..5d0e36b --- /dev/null +++ b/docs/modules/config.rst @@ -0,0 +1,19 @@ +fastreid.config +========================= + +Related tutorials: :doc:`../tutorials/configs`, :doc:`../tutorials/extend`. + +.. automodule:: fastreid.config + :members: + :undoc-members: + :show-inheritance: + :inherited-members: + + +Config References +----------------- + +.. literalinclude:: ../../fastreid/config/defaults.py + :language: python + :linenos: + :lines: 4- diff --git a/docs/modules/data.rst b/docs/modules/data.rst new file mode 100644 index 0000000..bcde5ee --- /dev/null +++ b/docs/modules/data.rst @@ -0,0 +1,96 @@ +fastreid.data +======================= + +.. automodule:: fastreid.data.build + :members: + :undoc-members: + :show-inheritance: + + +fastreid.data.data\_utils module +--------------------------------------- + +.. automodule:: fastreid.data.data_utils + :members: + :undoc-members: + :show-inheritance: + + +fastreid.data.datasets module +--------------------------------------- + +.. automodule:: fastreid.data.datasets.market1501 + :members: + +.. automodule:: fastreid.data.datasets.cuhk03 + :members: + +.. automodule:: fastreid.data.datasets.dukemtmcreid + :members: + +.. automodule:: fastreid.data.datasets.msmt17 + :members: + +.. automodule:: fastreid.data.datasets.AirportALERT + :members: + +.. automodule:: fastreid.data.datasets.iLIDS + :members: + +.. automodule:: fastreid.data.datasets.pku + :members: + +.. automodule:: fastreid.data.datasets.prai + :members: + +.. automodule:: fastreid.data.datasets.saivt + :members: + +.. automodule:: fastreid.data.datasets.sensereid + :members: + +.. automodule:: fastreid.data.datasets.sysu_mm + :members: + +.. automodule:: fastreid.data.datasets.thermalworld + :members: + +.. automodule:: fastreid.data.datasets.pes3d + :members: + +.. automodule:: fastreid.data.datasets.caviara + :members: + +.. automodule:: fastreid.data.datasets.viper + :members: + +.. automodule:: fastreid.data.datasets.lpw + :members: + +.. automodule:: fastreid.data.datasets.shinpuhkan + :members: + +.. automodule:: fastreid.data.datasets.wildtracker + :members: + +.. automodule:: fastreid.data.datasets.cuhk_sysu + :members: + + +fastreid.data.samplers module +--------------------------------------- + +.. automodule:: fastreid.data.samplers + :members: + :undoc-members: + :show-inheritance: + + +fastreid.data.transforms module +--------------------------------------- + +.. automodule:: fastreid.data.transforms + :members: + :undoc-members: + :show-inheritance: + :imported-members: diff --git a/docs/modules/data_transforms.rst b/docs/modules/data_transforms.rst new file mode 100644 index 0000000..b82125e --- /dev/null +++ b/docs/modules/data_transforms.rst @@ -0,0 +1,9 @@ +fastreid.data.transforms +==================================== + + +.. automodule:: fastreid.data.transforms + :members: + :undoc-members: + :show-inheritance: + :imported-members: diff --git a/docs/modules/engine.rst b/docs/modules/engine.rst new file mode 100644 index 0000000..66e3d6a --- /dev/null +++ b/docs/modules/engine.rst @@ -0,0 +1,24 @@ +fastreid.engine +========================= + +.. automodule:: fastreid.engine + :members: + :undoc-members: + :show-inheritance: + + +fastreid.engine.defaults module +--------------------------------- + +.. automodule:: fastreid.engine.defaults + :members: + :undoc-members: + :show-inheritance: + +fastreid.engine.hooks module +--------------------------------- + +.. automodule:: fastreid.engine.hooks + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/modules/evaluation.rst b/docs/modules/evaluation.rst new file mode 100644 index 0000000..007b68d --- /dev/null +++ b/docs/modules/evaluation.rst @@ -0,0 +1,7 @@ +fastreid.evaluation +============================= + +.. automodule:: fastreid.evaluation + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/modules/export.rst b/docs/modules/export.rst new file mode 100644 index 0000000..3d4ad21 --- /dev/null +++ b/docs/modules/export.rst @@ -0,0 +1,9 @@ +fastreid.export +========================= + +Related tutorial: :doc:`../tutorials/deployment`. + +.. automodule:: fastreid.export + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/modules/index.rst b/docs/modules/index.rst new file mode 100644 index 0000000..34cf084 --- /dev/null +++ b/docs/modules/index.rst @@ -0,0 +1,17 @@ +API Documentation +================== + +.. toctree:: + + checkpoint + config + data + data_transforms + engine + evaluation + layers + model_zoo + modeling + solver + utils + export diff --git a/docs/modules/layers.rst b/docs/modules/layers.rst new file mode 100644 index 0000000..9db621a --- /dev/null +++ b/docs/modules/layers.rst @@ -0,0 +1,7 @@ +fastreid.layers +========================= + +.. automodule:: fastreid.layers + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/modules/modeling.rst b/docs/modules/modeling.rst new file mode 100644 index 0000000..74b2966 --- /dev/null +++ b/docs/modules/modeling.rst @@ -0,0 +1,24 @@ +fastreid.modeling +=========================== + +.. automodule:: fastreid.modeling + :members: + :undoc-members: + :show-inheritance: + +Model Registries +----------------- + +These are different registries provided in modeling. +Each registry provide you the ability to replace it with your customized component, +without having to modify fastreid's code. + +Note that it is impossible to allow users to customize any line of code directly. +Even just to add one line at some place, +you'll likely need to find out the smallest registry which contains that line, +and register your component to that registry. + + +.. autodata:: fastreid.modeling.BACKBONE_REGISTRY +.. autodata:: fastreid.modeling.META_ARCH_REGISTRY +.. autodata:: fastreid.modeling.REID_HEADS_REGISTRY diff --git a/docs/modules/solver.rst b/docs/modules/solver.rst new file mode 100644 index 0000000..bacab33 --- /dev/null +++ b/docs/modules/solver.rst @@ -0,0 +1,7 @@ +fastreid.solver +========================= + +.. automodule:: fastreid.solver + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/modules/utils.rst b/docs/modules/utils.rst new file mode 100644 index 0000000..58cce50 --- /dev/null +++ b/docs/modules/utils.rst @@ -0,0 +1,80 @@ +fastreid.utils +======================== + +fastreid.utils.colormap module +-------------------------------- + +.. automodule:: fastreid.utils.colormap + :members: + :undoc-members: + :show-inheritance: + +fastreid.utils.comm module +---------------------------- + +.. automodule:: fastreid.utils.comm + :members: + :undoc-members: + :show-inheritance: + + +fastreid.utils.events module +------------------------------ + +.. automodule:: fastreid.utils.events + :members: + :undoc-members: + :show-inheritance: + + +fastreid.utils.logger module +------------------------------ + +.. automodule:: fastreid.utils.logger + :members: + :undoc-members: + :show-inheritance: + + +fastreid.utils.registry module +-------------------------------- + +.. automodule:: fastreid.utils.registry + :members: + :undoc-members: + :show-inheritance: + +fastreid.utils.memory module +---------------------------------- + +.. automodule:: fastreid.utils.memory + :members: + :undoc-members: + :show-inheritance: + + +fastreid.utils.analysis module +---------------------------------- + +.. automodule:: fastreid.utils.analysis + :members: + :undoc-members: + :show-inheritance: + + +fastreid.utils.visualizer module +---------------------------------- + +.. automodule:: fastreid.utils.visualizer + :members: + :undoc-members: + :show-inheritance: + +fastreid.utils.video\_visualizer module +----------------------------------------- + +.. automodule:: fastreid.utils.video_visualizer + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..54b184b --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,20 @@ +termcolor +numpy +tqdm +docutils==0.16 +# https://github.com/sphinx-doc/sphinx/commit/7acd3ada3f38076af7b2b5c9f3b60bb9c2587a3d +git+git://github.com/sphinx-doc/sphinx.git@7acd3ada3f38076af7b2b5c9f3b60bb9c2587a3d +recommonmark==0.6.0 +sphinx_rtd_theme +matplotlib +termcolor +yacs +tabulate +cloudpickle +Pillow +future +requests +six +git+git://github.com/facebookresearch/fvcore.git +https://download.pytorch.org/whl/cpu/torch-1.5.0%2Bcpu-cp37-cp37m-linux_x86_64.whl +https://download.pytorch.org/whl/cpu/torchvision-0.6.0%2Bcpu-cp37-cp37m-linux_x86_64.whl