* [PATCH 0/9] doc: config and build improvements
@ 2016-11-05 20:18 Jani Nikula
2016-11-05 20:18 ` [PATCH 1/9] doc/conf.py: add notmuch-emacs-mua to texinfo documents Jani Nikula
` (10 more replies)
0 siblings, 11 replies; 12+ messages in thread
From: Jani Nikula @ 2016-11-05 20:18 UTC (permalink / raw)
To: notmuch
Here's a bunch of fixes to the documentation config and build.
BR,
Jani.
Jani Nikula (9):
doc/conf.py: add notmuch-emacs-mua to texinfo documents
doc/conf.py: generate texinfo_documents list from man_pages list
doc/conf.py: abstract notmuch authors
doc/conf.py: reindent, whitespace clean man page, texinfo lists
doc/conf.py: include command name in texinfo document title
doc: fix references in notmuch-emacs.rst
build: do not touch roff files after sphinx-build
build: generate man page list from source files, not conf.py
build: only install known man pages
doc/.gitignore | 1 -
doc/Makefile.local | 33 +++++-----
doc/conf.py | 165 ++++++++++++++++++++------------------------------
doc/mkdocdeps.py | 18 ------
doc/notmuch-emacs.rst | 4 +-
5 files changed, 87 insertions(+), 134 deletions(-)
delete mode 100644 doc/mkdocdeps.py
--
2.1.4
^ permalink raw reply [flat|nested] 12+ messages in thread
* [PATCH 1/9] doc/conf.py: add notmuch-emacs-mua to texinfo documents
2016-11-05 20:18 [PATCH 0/9] doc: config and build improvements Jani Nikula
@ 2016-11-05 20:18 ` Jani Nikula
2016-11-05 20:18 ` [PATCH 2/9] doc/conf.py: generate texinfo_documents list from man_pages list Jani Nikula
` (9 subsequent siblings)
10 siblings, 0 replies; 12+ messages in thread
From: Jani Nikula @ 2016-11-05 20:18 UTC (permalink / raw)
To: notmuch
This was overlooked when adding the man page.
---
doc/conf.py | 3 +++
1 file changed, 3 insertions(+)
diff --git a/doc/conf.py b/doc/conf.py
index 8b9329662bf0..fce5a3afdfc2 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -153,6 +153,9 @@ texinfo_documents = [
('man1/notmuch-dump','notmuch-dump',u'notmuch Documentation',
u'Carl Worth and many others', 'notmuch-dump',
'creates a plain-text dump of the tags of each message','Miscellaneous'),
+('man1/notmuch-emacs-mua','notmuch-emacs-mua',u'notmuch Documentation',
+ u'Carl Worth and many others', 'notmuch-emacs-mua',
+ u'send mail with notmuch and emacs','Miscellaneous'),
('man5/notmuch-hooks','notmuch-hooks',u'notmuch Documentation',
u'Carl Worth and many others', 'notmuch-hooks',
'hooks for notmuch','Miscellaneous'),
--
2.1.4
^ permalink raw reply related [flat|nested] 12+ messages in thread
* [PATCH 2/9] doc/conf.py: generate texinfo_documents list from man_pages list
2016-11-05 20:18 [PATCH 0/9] doc: config and build improvements Jani Nikula
2016-11-05 20:18 ` [PATCH 1/9] doc/conf.py: add notmuch-emacs-mua to texinfo documents Jani Nikula
@ 2016-11-05 20:18 ` Jani Nikula
2016-11-05 20:18 ` [PATCH 3/9] doc/conf.py: abstract notmuch authors Jani Nikula
` (8 subsequent siblings)
10 siblings, 0 replies; 12+ messages in thread
From: Jani Nikula @ 2016-11-05 20:18 UTC (permalink / raw)
To: notmuch
No need to repeat mostly the same information twice in conf.py. We
probably want to have a corresponding texinfo document for all the man
pages. Python list comprehension to the rescue. (The reverse is not
true; we have a texinfo document for notmuch-emacs we don't want as a
man page.)
There should be no user visible changes.
---
doc/conf.py | 60 ++++++++++++------------------------------------------------
1 file changed, 12 insertions(+), 48 deletions(-)
diff --git a/doc/conf.py b/doc/conf.py
index fce5a3afdfc2..aa02b9a8bb7b 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -135,52 +135,16 @@ texinfo_documents = [
('notmuch-emacs', 'notmuch-emacs', u'notmuch Documentation',
u'Carl Worth and many others', 'notmuch-emacs',
'emacs based front-end for notmuch', 'Miscellaneous'),
-('man1/notmuch','notmuch',u'notmuch Documentation',
- u'Carl Worth and many others', 'notmuch',
- 'thread-based email index, search, and tagging','Miscellaneous'),
-('man1/notmuch-address','notmuch-address',u'notmuch Documentation',
- u'Carl Worth and many others', 'notmuch-address',
- 'output addresses from matching messages','Miscellaneous'),
-('man1/notmuch-compact','notmuch-compact',u'notmuch Documentation',
- u'Carl Worth and many others', 'notmuch-compact',
- 'compact the notmuch database','Miscellaneous'),
-('man1/notmuch-config','notmuch-config',u'notmuch Documentation',
- u'Carl Worth and many others', 'notmuch-config',
- 'access notmuch configuration file','Miscellaneous'),
-('man1/notmuch-count','notmuch-count',u'notmuch Documentation',
- u'Carl Worth and many others', 'notmuch-count',
- 'count messages matching the given search terms','Miscellaneous'),
-('man1/notmuch-dump','notmuch-dump',u'notmuch Documentation',
- u'Carl Worth and many others', 'notmuch-dump',
- 'creates a plain-text dump of the tags of each message','Miscellaneous'),
-('man1/notmuch-emacs-mua','notmuch-emacs-mua',u'notmuch Documentation',
- u'Carl Worth and many others', 'notmuch-emacs-mua',
- u'send mail with notmuch and emacs','Miscellaneous'),
-('man5/notmuch-hooks','notmuch-hooks',u'notmuch Documentation',
- u'Carl Worth and many others', 'notmuch-hooks',
- 'hooks for notmuch','Miscellaneous'),
-('man1/notmuch-insert','notmuch-insert',u'notmuch Documentation',
- u'Carl Worth and many others', 'notmuch-insert',
- 'add a message to the maildir and notmuch database','Miscellaneous'),
-('man1/notmuch-new','notmuch-new',u'notmuch Documentation',
- u'Carl Worth and many others', 'notmuch-new',
- 'incorporate new mail into the notmuch database','Miscellaneous'),
-('man1/notmuch-reply','notmuch-reply',u'notmuch Documentation',
- u'Carl Worth and many others', 'notmuch-reply',
- 'constructs a reply template for a set of messages','Miscellaneous'),
-('man1/notmuch-restore','notmuch-restore',u'notmuch Documentation',
- u'Carl Worth and many others', 'notmuch-restore',
- 'restores the tags from the given file (see notmuch dump)','Miscellaneous'),
-('man1/notmuch-search','notmuch-search',u'notmuch Documentation',
- u'Carl Worth and many others', 'notmuch-search',
- 'search for messages matching the given search terms','Miscellaneous'),
-('man7/notmuch-search-terms','notmuch-search-terms',u'notmuch Documentation',
- u'Carl Worth and many others', 'notmuch-search-terms',
- 'syntax for notmuch queries','Miscellaneous'),
-('man1/notmuch-show','notmuch-show',u'notmuch Documentation',
- u'Carl Worth and many others', 'notmuch-show',
- 'show messages matching the given search terms','Miscellaneous'),
-('man1/notmuch-tag','notmuch-tag',u'notmuch Documentation',
- u'Carl Worth and many others', 'notmuch-tag',
- 'add/remove tags for all messages matching the search terms','Miscellaneous'),
]
+
+# generate texinfo list from man page list
+texinfo_documents += [
+ (
+ x[0], # source start file
+ x[1], # target name
+ u'notmuch Documentation', # title
+ x[3][0], # author
+ x[1], # dir menu entry
+ x[2], # description
+ 'Miscellaneous' # category
+ ) for x in man_pages]
--
2.1.4
^ permalink raw reply related [flat|nested] 12+ messages in thread
* [PATCH 3/9] doc/conf.py: abstract notmuch authors
2016-11-05 20:18 [PATCH 0/9] doc: config and build improvements Jani Nikula
2016-11-05 20:18 ` [PATCH 1/9] doc/conf.py: add notmuch-emacs-mua to texinfo documents Jani Nikula
2016-11-05 20:18 ` [PATCH 2/9] doc/conf.py: generate texinfo_documents list from man_pages list Jani Nikula
@ 2016-11-05 20:18 ` Jani Nikula
2016-11-05 20:18 ` [PATCH 4/9] doc/conf.py: reindent, whitespace clean man page, texinfo lists Jani Nikula
` (7 subsequent siblings)
10 siblings, 0 replies; 12+ messages in thread
From: Jani Nikula @ 2016-11-05 20:18 UTC (permalink / raw)
To: notmuch
Don't repeat the same stuff so much. We probably don't want to track
individual authors for man/texinfo pages anyway.
No user visible changes.
---
doc/conf.py | 36 +++++++++++++++++++-----------------
1 file changed, 19 insertions(+), 17 deletions(-)
diff --git a/doc/conf.py b/doc/conf.py
index aa02b9a8bb7b..3cec01451f35 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -52,71 +52,73 @@ htmlhelp_basename = 'notmuchdoc'
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
+notmuch_authors = u'Carl Worth and many others'
+
man_pages = [
('man1/notmuch','notmuch',
u'thread-based email index, search, and tagging',
- [u'Carl Worth and many others'], 1),
+ [notmuch_authors], 1),
('man1/notmuch-address','notmuch-address',
u'output addresses from matching messages',
- [u'Carl Worth and many others'], 1),
+ [notmuch_authors], 1),
('man1/notmuch-compact','notmuch-compact',
u'compact the notmuch database',
- [u'Carl Worth and many others'], 1),
+ [notmuch_authors], 1),
('man1/notmuch-config','notmuch-config',
u'access notmuch configuration file',
- [u'Carl Worth and many others'], 1),
+ [notmuch_authors], 1),
('man1/notmuch-count','notmuch-count',
u'count messages matching the given search terms',
- [u'Carl Worth and many others'], 1),
+ [notmuch_authors], 1),
('man1/notmuch-dump','notmuch-dump',
u'creates a plain-text dump of the tags of each message',
- [u'Carl Worth and many others'], 1),
+ [notmuch_authors], 1),
('man1/notmuch-emacs-mua','notmuch-emacs-mua',
u'send mail with notmuch and emacs',
- [u'Carl Worth and many others'], 1),
+ [notmuch_authors], 1),
('man5/notmuch-hooks','notmuch-hooks',
u'hooks for notmuch',
- [u'Carl Worth and many others'], 5),
+ [notmuch_authors], 5),
('man1/notmuch-insert','notmuch-insert',
u'add a message to the maildir and notmuch database',
- [u'Carl Worth and many others'], 1),
+ [notmuch_authors], 1),
('man1/notmuch-new','notmuch-new',
u'incorporate new mail into the notmuch database',
- [u'Carl Worth and many others'], 1),
+ [notmuch_authors], 1),
('man1/notmuch-reply','notmuch-reply',
u'constructs a reply template for a set of messages',
- [u'Carl Worth and many others'], 1),
+ [notmuch_authors], 1),
('man1/notmuch-restore','notmuch-restore',
u'restores the tags from the given file (see notmuch dump)',
- [u'Carl Worth and many others'], 1),
+ [notmuch_authors], 1),
('man1/notmuch-search','notmuch-search',
u'search for messages matching the given search terms',
- [u'Carl Worth and many others'], 1),
+ [notmuch_authors], 1),
('man7/notmuch-search-terms','notmuch-search-terms',
u'syntax for notmuch queries',
- [u'Carl Worth and many others'], 7),
+ [notmuch_authors], 7),
('man1/notmuch-show','notmuch-show',
u'show messages matching the given search terms',
- [u'Carl Worth and many others'], 1),
+ [notmuch_authors], 1),
('man1/notmuch-tag','notmuch-tag',
u'add/remove tags for all messages matching the search terms',
- [u'Carl Worth and many others'], 1),
+ [notmuch_authors], 1),
]
@@ -133,7 +135,7 @@ texinfo_no_detailmenu = True
texinfo_documents = [
('notmuch-emacs', 'notmuch-emacs', u'notmuch Documentation',
- u'Carl Worth and many others', 'notmuch-emacs',
+ notmuch_authors, 'notmuch-emacs',
'emacs based front-end for notmuch', 'Miscellaneous'),
]
--
2.1.4
^ permalink raw reply related [flat|nested] 12+ messages in thread
* [PATCH 4/9] doc/conf.py: reindent, whitespace clean man page, texinfo lists
2016-11-05 20:18 [PATCH 0/9] doc: config and build improvements Jani Nikula
` (2 preceding siblings ...)
2016-11-05 20:18 ` [PATCH 3/9] doc/conf.py: abstract notmuch authors Jani Nikula
@ 2016-11-05 20:18 ` Jani Nikula
2016-11-05 20:18 ` [PATCH 5/9] doc/conf.py: include command name in texinfo document title Jani Nikula
` (6 subsequent siblings)
10 siblings, 0 replies; 12+ messages in thread
From: Jani Nikula @ 2016-11-05 20:18 UTC (permalink / raw)
To: notmuch
No functional changes.
---
doc/conf.py | 106 +++++++++++++++++++++++++++++-------------------------------
1 file changed, 52 insertions(+), 54 deletions(-)
diff --git a/doc/conf.py b/doc/conf.py
index 3cec01451f35..f8da1a422f9a 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -55,73 +55,71 @@ htmlhelp_basename = 'notmuchdoc'
notmuch_authors = u'Carl Worth and many others'
man_pages = [
+ ('man1/notmuch', 'notmuch',
+ u'thread-based email index, search, and tagging',
+ [notmuch_authors], 1),
-('man1/notmuch','notmuch',
- u'thread-based email index, search, and tagging',
- [notmuch_authors], 1),
+ ('man1/notmuch-address', 'notmuch-address',
+ u'output addresses from matching messages',
+ [notmuch_authors], 1),
-('man1/notmuch-address','notmuch-address',
- u'output addresses from matching messages',
- [notmuch_authors], 1),
+ ('man1/notmuch-compact', 'notmuch-compact',
+ u'compact the notmuch database',
+ [notmuch_authors], 1),
-('man1/notmuch-compact','notmuch-compact',
- u'compact the notmuch database',
- [notmuch_authors], 1),
+ ('man1/notmuch-config', 'notmuch-config',
+ u'access notmuch configuration file',
+ [notmuch_authors], 1),
-('man1/notmuch-config','notmuch-config',
- u'access notmuch configuration file',
- [notmuch_authors], 1),
+ ('man1/notmuch-count', 'notmuch-count',
+ u'count messages matching the given search terms',
+ [notmuch_authors], 1),
-('man1/notmuch-count','notmuch-count',
- u'count messages matching the given search terms',
- [notmuch_authors], 1),
+ ('man1/notmuch-dump', 'notmuch-dump',
+ u'creates a plain-text dump of the tags of each message',
+ [notmuch_authors], 1),
-('man1/notmuch-dump','notmuch-dump',
- u'creates a plain-text dump of the tags of each message',
- [notmuch_authors], 1),
+ ('man1/notmuch-emacs-mua', 'notmuch-emacs-mua',
+ u'send mail with notmuch and emacs',
+ [notmuch_authors], 1),
-('man1/notmuch-emacs-mua','notmuch-emacs-mua',
- u'send mail with notmuch and emacs',
- [notmuch_authors], 1),
+ ('man5/notmuch-hooks', 'notmuch-hooks',
+ u'hooks for notmuch',
+ [notmuch_authors], 5),
-('man5/notmuch-hooks','notmuch-hooks',
- u'hooks for notmuch',
- [notmuch_authors], 5),
+ ('man1/notmuch-insert', 'notmuch-insert',
+ u'add a message to the maildir and notmuch database',
+ [notmuch_authors], 1),
-('man1/notmuch-insert','notmuch-insert',
- u'add a message to the maildir and notmuch database',
- [notmuch_authors], 1),
+ ('man1/notmuch-new', 'notmuch-new',
+ u'incorporate new mail into the notmuch database',
+ [notmuch_authors], 1),
-('man1/notmuch-new','notmuch-new',
- u'incorporate new mail into the notmuch database',
- [notmuch_authors], 1),
+ ('man1/notmuch-reply', 'notmuch-reply',
+ u'constructs a reply template for a set of messages',
+ [notmuch_authors], 1),
-('man1/notmuch-reply','notmuch-reply',
- u'constructs a reply template for a set of messages',
- [notmuch_authors], 1),
+ ('man1/notmuch-restore', 'notmuch-restore',
+ u'restores the tags from the given file (see notmuch dump)',
+ [notmuch_authors], 1),
-('man1/notmuch-restore','notmuch-restore',
- u'restores the tags from the given file (see notmuch dump)',
- [notmuch_authors], 1),
+ ('man1/notmuch-search', 'notmuch-search',
+ u'search for messages matching the given search terms',
+ [notmuch_authors], 1),
-('man1/notmuch-search','notmuch-search',
- u'search for messages matching the given search terms',
- [notmuch_authors], 1),
-
-('man7/notmuch-search-terms','notmuch-search-terms',
- u'syntax for notmuch queries',
- [notmuch_authors], 7),
-
-('man1/notmuch-show','notmuch-show',
- u'show messages matching the given search terms',
- [notmuch_authors], 1),
-
-('man1/notmuch-tag','notmuch-tag',
- u'add/remove tags for all messages matching the search terms',
- [notmuch_authors], 1),
+ ('man7/notmuch-search-terms', 'notmuch-search-terms',
+ u'syntax for notmuch queries',
+ [notmuch_authors], 7),
+ ('man1/notmuch-show', 'notmuch-show',
+ u'show messages matching the given search terms',
+ [notmuch_authors], 1),
+ ('man1/notmuch-tag', 'notmuch-tag',
+ u'add/remove tags for all messages matching the search terms',
+ [notmuch_authors], 1),
]
+
# If true, show URL addresses after external links.
#man_show_urls = False
@@ -134,9 +132,9 @@ man_pages = [
texinfo_no_detailmenu = True
texinfo_documents = [
- ('notmuch-emacs', 'notmuch-emacs', u'notmuch Documentation',
- notmuch_authors, 'notmuch-emacs',
- 'emacs based front-end for notmuch', 'Miscellaneous'),
+ ('notmuch-emacs', 'notmuch-emacs', u'notmuch Documentation',
+ notmuch_authors, 'notmuch-emacs',
+ 'emacs based front-end for notmuch', 'Miscellaneous'),
]
# generate texinfo list from man page list
--
2.1.4
^ permalink raw reply related [flat|nested] 12+ messages in thread
* [PATCH 5/9] doc/conf.py: include command name in texinfo document title
2016-11-05 20:18 [PATCH 0/9] doc: config and build improvements Jani Nikula
` (3 preceding siblings ...)
2016-11-05 20:18 ` [PATCH 4/9] doc/conf.py: reindent, whitespace clean man page, texinfo lists Jani Nikula
@ 2016-11-05 20:18 ` Jani Nikula
2016-11-05 20:18 ` [PATCH 6/9] doc: fix references in notmuch-emacs.rst Jani Nikula
` (5 subsequent siblings)
10 siblings, 0 replies; 12+ messages in thread
From: Jani Nikula @ 2016-11-05 20:18 UTC (permalink / raw)
To: notmuch
Seems to make more sense than to have the same title for everything.
---
doc/conf.py | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/doc/conf.py b/doc/conf.py
index f8da1a422f9a..b6cfa1aa3499 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -132,7 +132,7 @@ man_pages = [
texinfo_no_detailmenu = True
texinfo_documents = [
- ('notmuch-emacs', 'notmuch-emacs', u'notmuch Documentation',
+ ('notmuch-emacs', 'notmuch-emacs', u'notmuch-emacs documentation',
notmuch_authors, 'notmuch-emacs',
'emacs based front-end for notmuch', 'Miscellaneous'),
]
@@ -142,7 +142,7 @@ texinfo_documents += [
(
x[0], # source start file
x[1], # target name
- u'notmuch Documentation', # title
+ x[1] + u' documentation', # title
x[3][0], # author
x[1], # dir menu entry
x[2], # description
--
2.1.4
^ permalink raw reply related [flat|nested] 12+ messages in thread
* [PATCH 6/9] doc: fix references in notmuch-emacs.rst
2016-11-05 20:18 [PATCH 0/9] doc: config and build improvements Jani Nikula
` (4 preceding siblings ...)
2016-11-05 20:18 ` [PATCH 5/9] doc/conf.py: include command name in texinfo document title Jani Nikula
@ 2016-11-05 20:18 ` Jani Nikula
2016-11-05 20:18 ` [PATCH 7/9] build: do not touch roff files after sphinx-build Jani Nikula
` (4 subsequent siblings)
10 siblings, 0 replies; 12+ messages in thread
From: Jani Nikula @ 2016-11-05 20:18 UTC (permalink / raw)
To: notmuch
Fix make sphinx-texinfo warnings:
WARNING: undefined label: notmuch-jump (if the link has no caption the
label must precede a section header)
WARNING: undefined label: notmuch-saved-searches (if the link has no
caption the label must precede a section header)
---
doc/notmuch-emacs.rst | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst
index d68542d349a0..5e25996f69b4 100644
--- a/doc/notmuch-emacs.rst
+++ b/doc/notmuch-emacs.rst
@@ -189,10 +189,12 @@ following key bindings:
``j``
Jump to saved searches using :ref:`notmuch-jump`.
+.. _notmuch-jump:
+
notmuch-jump
------------
-Saved searches configured through :ref:`notmuch-saved-searches` can
+Saved searches configured through :ref:`saved-searches` can
include a "shortcut key" that's accessible through notmuch-jump.
Pressing ``j`` anywhere in notmuch followed by the configured shortcut
key of a saved search will immediately jump to that saved search. For
--
2.1.4
^ permalink raw reply related [flat|nested] 12+ messages in thread
* [PATCH 7/9] build: do not touch roff files after sphinx-build
2016-11-05 20:18 [PATCH 0/9] doc: config and build improvements Jani Nikula
` (5 preceding siblings ...)
2016-11-05 20:18 ` [PATCH 6/9] doc: fix references in notmuch-emacs.rst Jani Nikula
@ 2016-11-05 20:18 ` Jani Nikula
2016-11-05 20:18 ` [PATCH 8/9] build: generate man page list from source files, not conf.py Jani Nikula
` (3 subsequent siblings)
10 siblings, 0 replies; 12+ messages in thread
From: Jani Nikula @ 2016-11-05 20:18 UTC (permalink / raw)
To: notmuch
If Sphinx fails to create any of the roff files, having touch create
them hides the errors until someone realizes, possibly much later,
that the resulting files are empty. (Note that gzip doesn't fail on
empty input files.) Sphinx will change the timestamps of any files it
has written anyway.
---
doc/Makefile.local | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/doc/Makefile.local b/doc/Makefile.local
index 8633cfcd3b51..5dc1cad489cc 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -53,7 +53,7 @@ else
@echo "Fatal: build dependency fail."
@false
endif
- touch ${MAN_ROFF_FILES} $@
+ touch $@
install-man: install-apidocs
--
2.1.4
^ permalink raw reply related [flat|nested] 12+ messages in thread
* [PATCH 8/9] build: generate man page list from source files, not conf.py
2016-11-05 20:18 [PATCH 0/9] doc: config and build improvements Jani Nikula
` (6 preceding siblings ...)
2016-11-05 20:18 ` [PATCH 7/9] build: do not touch roff files after sphinx-build Jani Nikula
@ 2016-11-05 20:18 ` Jani Nikula
2016-11-05 20:18 ` [PATCH 9/9] build: only install known man pages Jani Nikula
` (2 subsequent siblings)
10 siblings, 0 replies; 12+ messages in thread
From: Jani Nikula @ 2016-11-05 20:18 UTC (permalink / raw)
To: notmuch
Use $(wildcard ...) to generate the list of man pages based on the rst
source files present in the man page directories, instead of reading
conf.py. This has three main benefits:
1) This makes the man page build slightly less complicated and easier
to understand. At least there are fewer moving parts.
2) This makes the build fail if we add a man page rst file, but fail
to add it to conf.py.
3) We can use Sphinx constructs in conf.py that are not available when
importing the file into a normal python program such as
mkdocdeps.py.
---
doc/.gitignore | 1 -
doc/Makefile.local | 23 +++++++++++++----------
doc/mkdocdeps.py | 18 ------------------
3 files changed, 13 insertions(+), 29 deletions(-)
delete mode 100644 doc/mkdocdeps.py
diff --git a/doc/.gitignore b/doc/.gitignore
index d0da78e510f1..9fa35d08a95e 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -1,4 +1,3 @@
*.pyc
-docdeps.mk
_build
config.dox
diff --git a/doc/Makefile.local b/doc/Makefile.local
index 5dc1cad489cc..8a2f656bcad4 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -7,13 +7,23 @@ SPHINXOPTS := -q
SPHINXBUILD = sphinx-build
DOCBUILDDIR := $(dir)/_build
-mkdocdeps := $(PYTHON) $(srcdir)/$(dir)/mkdocdeps.py
-
# Internal variables.
ALLSPHINXOPTS := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(srcdir)/$(dir)
APIMAN := $(DOCBUILDDIR)/man/man3/notmuch.3
DOXYFILE := $(srcdir)/$(dir)/doxygen.cfg
+MAN1_RST := $(wildcard $(srcdir)/doc/man1/*.rst)
+MAN5_RST := $(wildcard $(srcdir)/doc/man5/*.rst)
+MAN7_RST := $(wildcard $(srcdir)/doc/man7/*.rst)
+MAN_RST_FILES := $(MAN1_RST) $(MAN5_RST) $(MAN7_RST)
+
+MAN1_ROFF := $(patsubst $(srcdir)/doc/%,$(DOCBUILDDIR)/man/%,$(MAN1_RST:.rst=.1))
+MAN5_ROFF := $(patsubst $(srcdir)/doc/%,$(DOCBUILDDIR)/man/%,$(MAN5_RST:.rst=.5))
+MAN7_ROFF := $(patsubst $(srcdir)/doc/%,$(DOCBUILDDIR)/man/%,$(MAN7_RST:.rst=.7))
+MAN_ROFF_FILES := $(MAN1_ROFF) $(MAN5_ROFF) $(MAN7_ROFF)
+
+MAN_GZIP_FILES := $(addsuffix .gz,${MAN_ROFF_FILES})
+
.PHONY: sphinx-html sphinx-texinfo sphinx-info
.PHONY: install-man build-man apidocs install-apidocs
@@ -30,10 +40,6 @@ sphinx-texinfo:
sphinx-info: sphinx-texinfo
make -C $(DOCBUILDDIR)/texinfo info
--include $(dir)/docdeps.mk
-
-MAN_GZIP_FILES := $(addsuffix .gz,${MAN_ROFF_FILES})
-
# Use the man page converter that is available. We should never depend
# on MAN_ROFF_FILES if a converter is not available.
${MAN_ROFF_FILES}: $(DOCBUILDDIR)/.roff.stamp
@@ -96,8 +102,5 @@ $(dir)/config.dox: version.stamp
echo "PROJECT_NAME = \"Notmuch $(VERSION)\"" > $@
echo "INPUT=${srcdir}/lib/notmuch.h" >> $@
-$(dir)/docdeps.mk: $(dir)/conf.py $(dir)/mkdocdeps.py
- $(mkdocdeps) $(srcdir)/doc $(DOCBUILDDIR) $@
-
-CLEAN := $(CLEAN) $(DOCBUILDDIR) $(dir)/docdeps.mk $(DOCBUILDDIR)/.roff.stamp
+CLEAN := $(CLEAN) $(DOCBUILDDIR) $(DOCBUILDDIR)/.roff.stamp
CLEAN := $(CLEAN) $(MAN_GZIP_FILES) $(MAN_ROFF_FILES) $(dir)/conf.pyc $(dir)/config.dox
diff --git a/doc/mkdocdeps.py b/doc/mkdocdeps.py
deleted file mode 100644
index b87fe3e80c0f..000000000000
--- a/doc/mkdocdeps.py
+++ /dev/null
@@ -1,18 +0,0 @@
-import sys
-
-srcdir = sys.argv[1]
-builddir = sys.argv[2]
-outfile = sys.argv[3]
-
-sys.path.insert(0, srcdir)
-import conf
-
-roff_files = []
-rst_files = []
-for page in conf.man_pages:
- rst_files = rst_files + ["{0:s}/{1:s}.rst".format(srcdir,page[0])]
- roff_files = roff_files + ["{0:s}/man/{1:s}.{2:d}".format(builddir,page[0],page[4])]
-
-with open(outfile, 'w') as out:
- out.write('MAN_ROFF_FILES := ' + ' \\\n\t'.join(roff_files) + '\n')
- out.write('MAN_RST_FILES := ' + ' \\\n\t'.join(rst_files) + '\n')
--
2.1.4
^ permalink raw reply related [flat|nested] 12+ messages in thread
* [PATCH 9/9] build: only install known man pages
2016-11-05 20:18 [PATCH 0/9] doc: config and build improvements Jani Nikula
` (7 preceding siblings ...)
2016-11-05 20:18 ` [PATCH 8/9] build: generate man page list from source files, not conf.py Jani Nikula
@ 2016-11-05 20:18 ` Jani Nikula
2016-11-16 17:36 ` [PATCH 0/9] doc: config and build improvements Tomi Ollila
2016-11-18 2:19 ` David Bremner
10 siblings, 0 replies; 12+ messages in thread
From: Jani Nikula @ 2016-11-05 20:18 UTC (permalink / raw)
To: notmuch
Install man pages based on $(MAN_GZIP_FILES), which directly
corresponds to the man page source rst files. This way we can filter
the man pages to be installed as needed.
---
doc/Makefile.local | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/doc/Makefile.local b/doc/Makefile.local
index 8a2f656bcad4..c6f05ca879c0 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -68,7 +68,7 @@ MAN_GZIP_FILES += ${APIMAN}.gz
apidocs: $(APIMAN)
install-apidocs: ${APIMAN}.gz
mkdir -p "$(DESTDIR)$(mandir)/man3"
- install -m0644 $(DOCBUILDDIR)/man/man3/*.3.gz $(DESTDIR)/$(mandir)/man3
+ install -m0644 $(filter %.3.gz,$(MAN_GZIP_FILES)) $(DESTDIR)/$(mandir)/man3
$(APIMAN): $(dir)/config.dox $(srcdir)/$(dir)/doxygen.cfg $(srcdir)/lib/notmuch.h
mkdir -p $(DOCBUILDDIR)/man/man3
@@ -92,9 +92,9 @@ install-man: ${MAN_GZIP_FILES}
mkdir -p "$(DESTDIR)$(mandir)/man1"
mkdir -p "$(DESTDIR)$(mandir)/man5"
mkdir -p "$(DESTDIR)$(mandir)/man7"
- install -m0644 $(DOCBUILDDIR)/man/man1/*.1.gz $(DESTDIR)/$(mandir)/man1
- install -m0644 $(DOCBUILDDIR)/man/man5/*.5.gz $(DESTDIR)/$(mandir)/man5
- install -m0644 $(DOCBUILDDIR)/man/man7/*.7.gz $(DESTDIR)/$(mandir)/man7
+ install -m0644 $(filter %.1.gz,$(MAN_GZIP_FILES)) $(DESTDIR)/$(mandir)/man1
+ install -m0644 $(filter %.5.gz,$(MAN_GZIP_FILES)) $(DESTDIR)/$(mandir)/man5
+ install -m0644 $(filter %.7.gz,$(MAN_GZIP_FILES)) $(DESTDIR)/$(mandir)/man7
cd $(DESTDIR)/$(mandir)/man1 && ln -sf notmuch.1.gz notmuch-setup.1.gz
endif
--
2.1.4
^ permalink raw reply related [flat|nested] 12+ messages in thread
* Re: [PATCH 0/9] doc: config and build improvements
2016-11-05 20:18 [PATCH 0/9] doc: config and build improvements Jani Nikula
` (8 preceding siblings ...)
2016-11-05 20:18 ` [PATCH 9/9] build: only install known man pages Jani Nikula
@ 2016-11-16 17:36 ` Tomi Ollila
2016-11-18 2:19 ` David Bremner
10 siblings, 0 replies; 12+ messages in thread
From: Tomi Ollila @ 2016-11-16 17:36 UTC (permalink / raw)
To: notmuch
On Sat, Nov 05 2016, Jani Nikula <jani@nikula.org> wrote:
> Here's a bunch of fixes to the documentation config and build.
>
> BR,
> Jani.
This series looks good to me.
Tomi
>
>
> Jani Nikula (9):
> doc/conf.py: add notmuch-emacs-mua to texinfo documents
> doc/conf.py: generate texinfo_documents list from man_pages list
> doc/conf.py: abstract notmuch authors
> doc/conf.py: reindent, whitespace clean man page, texinfo lists
> doc/conf.py: include command name in texinfo document title
> doc: fix references in notmuch-emacs.rst
> build: do not touch roff files after sphinx-build
> build: generate man page list from source files, not conf.py
> build: only install known man pages
>
> doc/.gitignore | 1 -
> doc/Makefile.local | 33 +++++-----
> doc/conf.py | 165 ++++++++++++++++++++------------------------------
> doc/mkdocdeps.py | 18 ------
> doc/notmuch-emacs.rst | 4 +-
> 5 files changed, 87 insertions(+), 134 deletions(-)
> delete mode 100644 doc/mkdocdeps.py
>
> --
> 2.1.4
>
> _______________________________________________
> notmuch mailing list
> notmuch@notmuchmail.org
> https://notmuchmail.org/mailman/listinfo/notmuch
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 0/9] doc: config and build improvements
2016-11-05 20:18 [PATCH 0/9] doc: config and build improvements Jani Nikula
` (9 preceding siblings ...)
2016-11-16 17:36 ` [PATCH 0/9] doc: config and build improvements Tomi Ollila
@ 2016-11-18 2:19 ` David Bremner
10 siblings, 0 replies; 12+ messages in thread
From: David Bremner @ 2016-11-18 2:19 UTC (permalink / raw)
To: Jani Nikula, notmuch
Jani Nikula <jani@nikula.org> writes:
> Here's a bunch of fixes to the documentation config and build.
>
pushed to master
d
^ permalink raw reply [flat|nested] 12+ messages in thread
end of thread, other threads:[~2016-11-18 2:19 UTC | newest]
Thread overview: 12+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-11-05 20:18 [PATCH 0/9] doc: config and build improvements Jani Nikula
2016-11-05 20:18 ` [PATCH 1/9] doc/conf.py: add notmuch-emacs-mua to texinfo documents Jani Nikula
2016-11-05 20:18 ` [PATCH 2/9] doc/conf.py: generate texinfo_documents list from man_pages list Jani Nikula
2016-11-05 20:18 ` [PATCH 3/9] doc/conf.py: abstract notmuch authors Jani Nikula
2016-11-05 20:18 ` [PATCH 4/9] doc/conf.py: reindent, whitespace clean man page, texinfo lists Jani Nikula
2016-11-05 20:18 ` [PATCH 5/9] doc/conf.py: include command name in texinfo document title Jani Nikula
2016-11-05 20:18 ` [PATCH 6/9] doc: fix references in notmuch-emacs.rst Jani Nikula
2016-11-05 20:18 ` [PATCH 7/9] build: do not touch roff files after sphinx-build Jani Nikula
2016-11-05 20:18 ` [PATCH 8/9] build: generate man page list from source files, not conf.py Jani Nikula
2016-11-05 20:18 ` [PATCH 9/9] build: only install known man pages Jani Nikula
2016-11-16 17:36 ` [PATCH 0/9] doc: config and build improvements Tomi Ollila
2016-11-18 2:19 ` David Bremner
Code repositories for project(s) associated with this public inbox
https://yhetil.org/notmuch.git/
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).