From d2e7377c0fdbc1ae5f54bd82a4b0e56168bf58c1 Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Wed, 22 Aug 2018 00:07:42 +0530 Subject: [PATCH 1/2] Reorganize pip's docs folder --- docs/__init__.py | 1 - docs/conf.py | 14 +++++++------- docs/{ => html}/cookbook.rst | 0 docs/{ => html/development}/configuration.rst | 2 +- docs/{ => html}/development/contributing.rst | 0 docs/{ => html}/development/getting-started.rst | 0 docs/{ => html}/development/index.rst | 0 docs/{ => html}/development/release-process.rst | 0 docs/{ => html}/index.rst | 0 docs/{ => html}/installing.rst | 0 docs/{ => html}/logic.rst | 0 docs/{ => html}/news.rst | 2 +- docs/{ => html}/quickstart.rst | 0 docs/{ => html}/reference/index.rst | 0 docs/{ => html}/reference/pip.rst | 0 docs/{ => html}/reference/pip_check.rst | 0 docs/{ => html}/reference/pip_config.rst | 0 docs/{ => html}/reference/pip_download.rst | 0 docs/{ => html}/reference/pip_freeze.rst | 0 docs/{ => html}/reference/pip_hash.rst | 0 docs/{ => html}/reference/pip_install.rst | 0 docs/{ => html}/reference/pip_list.rst | 0 docs/{ => html}/reference/pip_search.rst | 0 docs/{ => html}/reference/pip_show.rst | 0 docs/{ => html}/reference/pip_uninstall.rst | 0 docs/{ => html}/reference/pip_wheel.rst | 0 docs/{ => html}/usage.rst | 0 docs/{ => html}/user_guide.rst | 0 docs/man/{pip.rst => index.rst} | 0 docs/{pipext.py => pip_sphinxext.py} | 0 tox.ini | 8 ++++---- 31 files changed, 13 insertions(+), 14 deletions(-) delete mode 100644 docs/__init__.py rename docs/{ => html}/cookbook.rst (100%) rename docs/{ => html/development}/configuration.rst (72%) rename docs/{ => html}/development/contributing.rst (100%) rename docs/{ => html}/development/getting-started.rst (100%) rename docs/{ => html}/development/index.rst (100%) rename docs/{ => html}/development/release-process.rst (100%) rename docs/{ => html}/index.rst (100%) rename docs/{ => html}/installing.rst (100%) rename docs/{ => html}/logic.rst (100%) rename docs/{ => html}/news.rst (60%) rename docs/{ => html}/quickstart.rst (100%) rename docs/{ => html}/reference/index.rst (100%) rename docs/{ => html}/reference/pip.rst (100%) rename docs/{ => html}/reference/pip_check.rst (100%) rename docs/{ => html}/reference/pip_config.rst (100%) rename docs/{ => html}/reference/pip_download.rst (100%) rename docs/{ => html}/reference/pip_freeze.rst (100%) rename docs/{ => html}/reference/pip_hash.rst (100%) rename docs/{ => html}/reference/pip_install.rst (100%) rename docs/{ => html}/reference/pip_list.rst (100%) rename docs/{ => html}/reference/pip_search.rst (100%) rename docs/{ => html}/reference/pip_show.rst (100%) rename docs/{ => html}/reference/pip_uninstall.rst (100%) rename docs/{ => html}/reference/pip_wheel.rst (100%) rename docs/{ => html}/usage.rst (100%) rename docs/{ => html}/user_guide.rst (100%) rename docs/man/{pip.rst => index.rst} (100%) rename docs/{pipext.py => pip_sphinxext.py} (100%) diff --git a/docs/__init__.py b/docs/__init__.py deleted file mode 100644 index b430650996d..00000000000 --- a/docs/__init__.py +++ /dev/null @@ -1 +0,0 @@ -# docs module diff --git a/docs/conf.py b/docs/conf.py index 5e48423412b..68c949d2ea7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,10 +18,11 @@ on_rtd = os.environ.get('READTHEDOCS', None) == 'True' +here = 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, here) # sys.path.append(os.path.join(os.path.dirname(__file__), '../')) # -- General configuration ---------------------------------------------------- @@ -29,7 +30,7 @@ # 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(here, '..', '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 b/docs/html/cookbook.rst similarity index 100% rename from docs/cookbook.rst rename to docs/html/cookbook.rst diff --git a/docs/configuration.rst b/docs/html/development/configuration.rst similarity index 72% rename from docs/configuration.rst rename to docs/html/development/configuration.rst index c0831fd70be..adf8207dd8f 100644 --- a/docs/configuration.rst +++ b/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 `. +This content is now covered in the :ref:`Configuration` section of the :doc:`User Guide `. diff --git a/docs/development/contributing.rst b/docs/html/development/contributing.rst similarity index 100% rename from docs/development/contributing.rst rename to docs/html/development/contributing.rst diff --git a/docs/development/getting-started.rst b/docs/html/development/getting-started.rst similarity index 100% rename from docs/development/getting-started.rst rename to docs/html/development/getting-started.rst diff --git a/docs/development/index.rst b/docs/html/development/index.rst similarity index 100% rename from docs/development/index.rst rename to docs/html/development/index.rst diff --git a/docs/development/release-process.rst b/docs/html/development/release-process.rst similarity index 100% rename from docs/development/release-process.rst rename to docs/html/development/release-process.rst diff --git a/docs/index.rst b/docs/html/index.rst similarity index 100% rename from docs/index.rst rename to docs/html/index.rst diff --git a/docs/installing.rst b/docs/html/installing.rst similarity index 100% rename from docs/installing.rst rename to docs/html/installing.rst diff --git a/docs/logic.rst b/docs/html/logic.rst similarity index 100% rename from docs/logic.rst rename to docs/html/logic.rst diff --git a/docs/news.rst b/docs/html/news.rst similarity index 60% rename from docs/news.rst rename to docs/html/news.rst index 3938e7a7928..1f6bfbf8ec3 100644 --- a/docs/news.rst +++ b/docs/html/news.rst @@ -2,4 +2,4 @@ Release Notes ============= -.. include:: ../NEWS.rst +.. include:: ../../NEWS.rst diff --git a/docs/quickstart.rst b/docs/html/quickstart.rst similarity index 100% rename from docs/quickstart.rst rename to docs/html/quickstart.rst diff --git a/docs/reference/index.rst b/docs/html/reference/index.rst similarity index 100% rename from docs/reference/index.rst rename to docs/html/reference/index.rst diff --git a/docs/reference/pip.rst b/docs/html/reference/pip.rst similarity index 100% rename from docs/reference/pip.rst rename to docs/html/reference/pip.rst diff --git a/docs/reference/pip_check.rst b/docs/html/reference/pip_check.rst similarity index 100% rename from docs/reference/pip_check.rst rename to docs/html/reference/pip_check.rst diff --git a/docs/reference/pip_config.rst b/docs/html/reference/pip_config.rst similarity index 100% rename from docs/reference/pip_config.rst rename to docs/html/reference/pip_config.rst diff --git a/docs/reference/pip_download.rst b/docs/html/reference/pip_download.rst similarity index 100% rename from docs/reference/pip_download.rst rename to docs/html/reference/pip_download.rst diff --git a/docs/reference/pip_freeze.rst b/docs/html/reference/pip_freeze.rst similarity index 100% rename from docs/reference/pip_freeze.rst rename to docs/html/reference/pip_freeze.rst diff --git a/docs/reference/pip_hash.rst b/docs/html/reference/pip_hash.rst similarity index 100% rename from docs/reference/pip_hash.rst rename to docs/html/reference/pip_hash.rst diff --git a/docs/reference/pip_install.rst b/docs/html/reference/pip_install.rst similarity index 100% rename from docs/reference/pip_install.rst rename to docs/html/reference/pip_install.rst diff --git a/docs/reference/pip_list.rst b/docs/html/reference/pip_list.rst similarity index 100% rename from docs/reference/pip_list.rst rename to docs/html/reference/pip_list.rst diff --git a/docs/reference/pip_search.rst b/docs/html/reference/pip_search.rst similarity index 100% rename from docs/reference/pip_search.rst rename to docs/html/reference/pip_search.rst diff --git a/docs/reference/pip_show.rst b/docs/html/reference/pip_show.rst similarity index 100% rename from docs/reference/pip_show.rst rename to docs/html/reference/pip_show.rst diff --git a/docs/reference/pip_uninstall.rst b/docs/html/reference/pip_uninstall.rst similarity index 100% rename from docs/reference/pip_uninstall.rst rename to docs/html/reference/pip_uninstall.rst diff --git a/docs/reference/pip_wheel.rst b/docs/html/reference/pip_wheel.rst similarity index 100% rename from docs/reference/pip_wheel.rst rename to docs/html/reference/pip_wheel.rst diff --git a/docs/usage.rst b/docs/html/usage.rst similarity index 100% rename from docs/usage.rst rename to docs/html/usage.rst diff --git a/docs/user_guide.rst b/docs/html/user_guide.rst similarity index 100% rename from docs/user_guide.rst rename to docs/html/user_guide.rst diff --git a/docs/man/pip.rst b/docs/man/index.rst similarity index 100% rename from docs/man/pip.rst rename to docs/man/index.rst diff --git a/docs/pipext.py b/docs/pip_sphinxext.py similarity index 100% rename from docs/pipext.py rename to docs/pip_sphinxext.py diff --git a/tox.ini b/tox.ini index d314f203d72..371ae17f854 100644 --- a/tox.ini +++ b/tox.ini @@ -19,12 +19,12 @@ 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 +basepython = python3.6 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 -c docs -d {envtmpdir}/doctrees/html -b html docs/html docs/build/html + sphinx-build -W -c docs -d {envtmpdir}/doctrees/man -b man docs/man docs/build/man [testenv:packaging] skip_install = True From 20f672c4e61f3f4f0bcc67d76c6c2713a4534fdc Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Wed, 22 Aug 2018 11:33:19 +0530 Subject: [PATCH 2/2] Move conf.py into the html directory, to be compatible with RTD Also add a small comment explaining why this has been done. --- docs/{ => html}/conf.py | 6 +++--- tox.ini | 10 +++++++--- 2 files changed, 10 insertions(+), 6 deletions(-) rename docs/{ => html}/conf.py (98%) diff --git a/docs/conf.py b/docs/html/conf.py similarity index 98% rename from docs/conf.py rename to docs/html/conf.py index 68c949d2ea7..bf8ed022808 100644 --- a/docs/conf.py +++ b/docs/html/conf.py @@ -18,11 +18,11 @@ on_rtd = os.environ.get('READTHEDOCS', None) == 'True' -here = os.path.dirname(__file__) +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, here) +sys.path.insert(0, docs_dir) # sys.path.append(os.path.join(os.path.dirname(__file__), '../')) # -- General configuration ---------------------------------------------------- @@ -70,7 +70,7 @@ # read the version direct from the __init__.py file. (Yes, this is # fragile, but it works...) -pip_init = os.path.join(here, '..', '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) diff --git a/tox.ini b/tox.ini index 371ae17f854..082af73ef9a 100644 --- a/tox.ini +++ b/tox.ini @@ -21,10 +21,14 @@ commands = pytest --timeout 300 --cov=pip --cov-report=term-missing --cov-report [testenv:docs] # Don't skip install here since pip_sphinxext uses pip's internals. deps = -r{toxinidir}/tools/docs-requirements.txt -basepython = python3.6 +basepython = python2.7 commands = - sphinx-build -W -c docs -d {envtmpdir}/doctrees/html -b html docs/html docs/build/html - sphinx-build -W -c docs -d {envtmpdir}/doctrees/man -b man docs/man 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