Merge pull request #5724 from pradyunsg/docs/reorganize

Reorganize pip's docs folder
pypa · Aug 24, 2018 · 404838a · 404838a
2 parents eeacf0e + 20f672c
commit 404838a
Show file tree

Hide file tree

Showing 31 changed files with 16 additions and 13 deletions.
diff --git a/docs/__init__.py b/docs/__init__.py
diff --git a/docs/conf.py → docs/html/conf.py b/docs/conf.py → docs/html/conf.py
@@ -18,18 +18,19 @@
 
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
+docs_dir = os.path.dirname(os.path.dirname(__file__))
 # 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.
-sys.path.insert(0, os.path.abspath(os.pardir))
+sys.path.insert(0, docs_dir)
 # sys.path.append(os.path.join(os.path.dirname(__file__), '../'))
 
 # -- General configuration ----------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 # extensions = ['sphinx.ext.autodoc']
-extensions = ['sphinx.ext.extlinks', 'docs.pipext', 'sphinx.ext.intersphinx']
+extensions = ['sphinx.ext.extlinks', 'pip_sphinxext', 'sphinx.ext.intersphinx']
 
 # intersphinx
 intersphinx_cache_limit = 0
@@ -68,9 +69,8 @@
 # Rather than trying to force RTD to install pip properly, we'll simply
 # read the version direct from the __init__.py file. (Yes, this is
 # fragile, but it works...)
-root = os.path.dirname(os.path.dirname(__file__))
-pip_init = os.path.join(root, 'src', 'pip', '__init__.py')
 
+pip_init = os.path.join(docs_dir, '..', 'src', 'pip', '__init__.py')
 with open(pip_init) as f:
     for line in f:
         m = re.match(r'__version__ = "(.*)"', line)
@@ -102,7 +102,7 @@
 
 # List of directories, relative to source directory, that shouldn't be searched
 # for source files.
-exclude_patterns = ['build/', 'man/']
+exclude_patterns = ['build/']
 
 # The reST default role (used for this markup: `text`) to use for all documents
 # default_role = None
@@ -253,7 +253,7 @@
 # List of manual pages generated
 man_pages = [
     (
-        'man/pip',
+        'index',
         'pip',
         u'package manager for Python packages',
         u'pip developers',
@@ -264,7 +264,7 @@
 # Here, we crawl the entire man/commands/ directory and list every file with
 # appropriate name and details
 for fname in glob.glob('man/commands/*.rst'):
-    fname_base = fname[:-4]
+    fname_base = fname[4:-4]
     outname = 'pip-' + fname_base[13:]
     description = u'description of {} command'.format(
         outname.replace('-', ' ')

diff --git a/docs/cookbook.rst → docs/html/cookbook.rst b/docs/cookbook.rst → docs/html/cookbook.rst
diff --git a/docs/configuration.rst → docs/html/development/configuration.rst b/docs/configuration.rst → docs/html/development/configuration.rst
@@ -3,4 +3,4 @@
 Configuration
 =============
 
-This content is now covered in the :ref:`Configuration` section of the :doc:`User Guide <user_guide>`.
+This content is now covered in the :ref:`Configuration` section of the :doc:`User Guide </user_guide>`.
diff --git a/docs/development/contributing.rst → docs/html/development/contributing.rst b/docs/development/contributing.rst → docs/html/development/contributing.rst
diff --git a/docs/development/getting-started.rst → docs/html/development/getting-started.rst b/docs/development/getting-started.rst → docs/html/development/getting-started.rst
diff --git a/docs/development/index.rst → docs/html/development/index.rst b/docs/development/index.rst → docs/html/development/index.rst
diff --git a/docs/development/release-process.rst → docs/html/development/release-process.rst b/docs/development/release-process.rst → docs/html/development/release-process.rst
diff --git a/docs/index.rst → docs/html/index.rst b/docs/index.rst → docs/html/index.rst
diff --git a/docs/installing.rst → docs/html/installing.rst b/docs/installing.rst → docs/html/installing.rst
diff --git a/docs/logic.rst → docs/html/logic.rst b/docs/logic.rst → docs/html/logic.rst
diff --git a/docs/news.rst → docs/html/news.rst b/docs/news.rst → docs/html/news.rst
@@ -2,4 +2,4 @@
 Release Notes
 =============
 
-.. include:: ../NEWS.rst
+.. include:: ../../NEWS.rst
diff --git a/docs/quickstart.rst → docs/html/quickstart.rst b/docs/quickstart.rst → docs/html/quickstart.rst
diff --git a/docs/reference/index.rst → docs/html/reference/index.rst b/docs/reference/index.rst → docs/html/reference/index.rst
diff --git a/docs/reference/pip.rst → docs/html/reference/pip.rst b/docs/reference/pip.rst → docs/html/reference/pip.rst
diff --git a/docs/reference/pip_check.rst → docs/html/reference/pip_check.rst b/docs/reference/pip_check.rst → docs/html/reference/pip_check.rst
diff --git a/docs/reference/pip_config.rst → docs/html/reference/pip_config.rst b/docs/reference/pip_config.rst → docs/html/reference/pip_config.rst
diff --git a/docs/reference/pip_download.rst → docs/html/reference/pip_download.rst b/docs/reference/pip_download.rst → docs/html/reference/pip_download.rst
diff --git a/docs/reference/pip_freeze.rst → docs/html/reference/pip_freeze.rst b/docs/reference/pip_freeze.rst → docs/html/reference/pip_freeze.rst
diff --git a/docs/reference/pip_hash.rst → docs/html/reference/pip_hash.rst b/docs/reference/pip_hash.rst → docs/html/reference/pip_hash.rst
diff --git a/docs/reference/pip_install.rst → docs/html/reference/pip_install.rst b/docs/reference/pip_install.rst → docs/html/reference/pip_install.rst
diff --git a/docs/reference/pip_list.rst → docs/html/reference/pip_list.rst b/docs/reference/pip_list.rst → docs/html/reference/pip_list.rst
diff --git a/docs/reference/pip_search.rst → docs/html/reference/pip_search.rst b/docs/reference/pip_search.rst → docs/html/reference/pip_search.rst
diff --git a/docs/reference/pip_show.rst → docs/html/reference/pip_show.rst b/docs/reference/pip_show.rst → docs/html/reference/pip_show.rst
diff --git a/docs/reference/pip_uninstall.rst → docs/html/reference/pip_uninstall.rst b/docs/reference/pip_uninstall.rst → docs/html/reference/pip_uninstall.rst
diff --git a/docs/reference/pip_wheel.rst → docs/html/reference/pip_wheel.rst b/docs/reference/pip_wheel.rst → docs/html/reference/pip_wheel.rst
diff --git a/docs/usage.rst → docs/html/usage.rst b/docs/usage.rst → docs/html/usage.rst
diff --git a/docs/user_guide.rst → docs/html/user_guide.rst b/docs/user_guide.rst → docs/html/user_guide.rst
diff --git a/docs/man/pip.rst → docs/man/index.rst b/docs/man/pip.rst → docs/man/index.rst
diff --git a/docs/pipext.py → docs/pip_sphinxext.py b/docs/pipext.py → docs/pip_sphinxext.py
diff --git a/tox.ini b/tox.ini
@@ -19,12 +19,16 @@ basepython = python3
 commands = pytest --timeout 300 --cov=pip --cov-report=term-missing --cov-report=xml --cov-report=html tests/unit {posargs}
 
 [testenv:docs]
-# Don't skip install here since docs.pipext uses pip's internals.
+# Don't skip install here since pip_sphinxext uses pip's internals.
 deps = -r{toxinidir}/tools/docs-requirements.txt
 basepython = python2.7
 commands =
-    sphinx-build -W -d {envtmpdir}/doctrees -b html docs docs/build/html
-    sphinx-build -W -d {envtmpdir}/doctrees -b man  docs docs/build/man
+    sphinx-build -W -d {envtmpdir}/doctrees/html -b html docs/html docs/build/html
+    # Having the conf.py in the docs/html is weird but needed because we
+    # can not use a different configuration directory vs source directory on RTD
+    # currently -- https://github.com/rtfd/readthedocs.org/issues/1543.
+    # That is why we have a "-c docs/html" in the next line.
+    sphinx-build -W -d {envtmpdir}/doctrees/man -b man docs/man docs/build/man -c docs/html
 
 [testenv:packaging]
 skip_install = True