From f3f63c0f82188cf73db7190923079e308410428c Mon Sep 17 00:00:00 2001 From: Eli Schwartz Date: Wed, 17 Jul 2019 22:53:17 -0400 Subject: [PATCH 1/4] docs: fix manpage names being truncated In commit d2e7377c0fdbc1ae5f54bd82a4b0e56168bf58c1, the documentation directories were reorganized, resulting in `fname_base` (the path that Sphinx looked for source files) to no longer expect the leading 'man/'. This was always also stripped from the `outname`, which now strips four characters twice over. Fix by reducing the stripped length to only the length of the prefix in fname_base itself. --- docs/html/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/html/conf.py b/docs/html/conf.py index 2fc71c5f8..f857c6fd7 100644 --- a/docs/html/conf.py +++ b/docs/html/conf.py @@ -277,7 +277,7 @@ man_pages = [ # appropriate name and details for fname in glob.glob('man/commands/*.rst'): fname_base = fname[4:-4] - outname = 'pip-' + fname_base[13:] + outname = 'pip-' + fname_base[9:] description = u'description of {} command'.format( outname.replace('-', ' ') ) From f2cbcd190f1b806153b5eda649428f59baf08b4d Mon Sep 17 00:00:00 2001 From: Eli Schwartz Date: Wed, 17 Jul 2019 22:53:22 -0400 Subject: [PATCH 2/4] docs: check that the subcommand manpages are actually found and being used --- docs/html/conf.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/html/conf.py b/docs/html/conf.py index f857c6fd7..9fc255477 100644 --- a/docs/html/conf.py +++ b/docs/html/conf.py @@ -275,7 +275,10 @@ man_pages = [ # 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'): +raw_subcommands = glob.glob('man/commands/*.rst') +if not raw_subcommands: + raise FileNotFoundError('The individual subcommand manpages could not be found!') +for fname in raw_subcommands: fname_base = fname[4:-4] outname = 'pip-' + fname_base[9:] description = u'description of {} command'.format( From 1350b95dee880f6d36c97f29d825ac59ce06e462 Mon Sep 17 00:00:00 2001 From: Eli Schwartz Date: Wed, 17 Jul 2019 22:54:38 -0400 Subject: [PATCH 3/4] docs: fix manpage generation This was broken in commit 20f672c4e61f3f4f0bcc67d76c6c2713a4534fdc, which reorganized the conf.py file into the html subdirectory. See: https://github.com/pypa/pip/pull/5724 https://github.com/readthedocs/readthedocs.org/issues/1543 This broke the relative manpage globbing because Sphinx will os.chdir() into the directory location of conf.py before evaluating it, so the globbing returned nothing at all. As a result, while the main pip(1) manpage continued to be built, no pip-*(1) subcommand manpages were built. --- docs/html/conf.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/html/conf.py b/docs/html/conf.py index 9fc255477..99386026a 100644 --- a/docs/html/conf.py +++ b/docs/html/conf.py @@ -275,11 +275,12 @@ man_pages = [ # Here, we crawl the entire man/commands/ directory and list every file with # appropriate name and details -raw_subcommands = glob.glob('man/commands/*.rst') +man_dir = os.path.join(docs_dir, 'man/') +raw_subcommands = glob.glob(os.path.join(man_dir, 'commands/*.rst')) if not raw_subcommands: raise FileNotFoundError('The individual subcommand manpages could not be found!') for fname in raw_subcommands: - fname_base = fname[4:-4] + fname_base = fname[len(man_dir):-4] outname = 'pip-' + fname_base[9:] description = u'description of {} command'.format( outname.replace('-', ' ') From 179902986bb49dacfa04b3e3080a64cb13f9d79e Mon Sep 17 00:00:00 2001 From: Eli Schwartz Date: Wed, 17 Jul 2019 22:58:17 -0400 Subject: [PATCH 4/4] Add news fragment --- news/6724.doc | 1 + 1 file changed, 1 insertion(+) create mode 100644 news/6724.doc diff --git a/news/6724.doc b/news/6724.doc new file mode 100644 index 000000000..eae5303d0 --- /dev/null +++ b/news/6724.doc @@ -0,0 +1 @@ +Fix generation of subcommand manpages.