( )⚙ D6063 setup: define build_doc command

This is an archive of the discontinued Mercurial Phabricator instance.

Differential D6063

setup: define build_doc command
ClosedPublic

Authored by indygreg on Mar 3 2019, 6:51 PM.

Details

Reviewers
None
Group Reviewers
hg-reviewers
Commits
rHGd80d48928eb1: setup: define build_doc command
Summary

Currently, various processes for packaging Mercurial state to
manually invoke make -C doc in order to generate the documentation.
This Makefile merely invokes gendoc.py and runrst to produce
man pages and HTML pages.

Not all environments may have the ability to easily run
Makefiles. Windows is notably in this set.

This commit ports the man page and HTML generation logic from
doc/Makefile to setup.py. We introduce a new build_doc command
which generates documentation by calling gendoc.py and runrst.
The documentation can now be built via pure Python by running
python setup.py build_doc.

We don't implement dependency tracking because IMO it is more
effort than it is worth.

We could potentially remove the duplicated functionality in
doc/Makefile. But I'm not sure what all is depending on it. So
I plan to keep it around.

  1. no-check-commit because forced foo_bar function names

Diff Detail

Repository
rHG Mercurial
Lint
Lint Skipped
Unit
Unit Tests Skipped

Event Timeline

indygreg created this revision.Mar 3 2019, 6:51 PM
Closed by commit rHGd80d48928eb1: setup: define build_doc command (authored by indygreg). · Explain WhyMar 5 2019, 10:24 AM
This revision was automatically updated to reflect the committed changes.

Revision Contents
Changeset List

PathPackages
Mdoc/Makefile (1 line)
Msetup.py (116 lines)

Diff 14328

doc/Makefile

export HGENCODING=UTF-8 export HGENCODING=UTF-8
all: man html all: man html
man: $(MAN) man: $(MAN)
html: $(HTML) html: $(HTML)
# This logic is duplicated in setup.py:hgbuilddoc()
common.txt $(SOURCES) $(SOURCES:%.txt=%.gendoc.txt): $(GENDOC) common.txt $(SOURCES) $(SOURCES:%.txt=%.gendoc.txt): $(GENDOC)
${PYTHON} gendoc.py "$(basename $@)" > $@.tmp ${PYTHON} gendoc.py "$(basename $@)" > $@.tmp
mv $@.tmp $@ mv $@.tmp $@
%: %.txt %.gendoc.txt common.txt %: %.txt %.gendoc.txt common.txt
$(PYTHON) runrst hgmanpage $(RSTARGS) --halt warning \ $(PYTHON) runrst hgmanpage $(RSTARGS) --halt warning \
--strip-elements-with-class htmlonly $*.txt $* --strip-elements-with-class htmlonly $*.txt $*

setup.py

import py2exe import py2exe
py2exe.Distribution # silence unused import warning py2exe.Distribution # silence unused import warning
py2exeloaded = True py2exeloaded = True
# import py2exe's patched Distribution class # import py2exe's patched Distribution class
from distutils.core import Distribution from distutils.core import Distribution
except ImportError: except ImportError:
py2exeloaded = False py2exeloaded = False
def runcmd(cmd, env): def runcmd(cmd, env, cwd=None):
p = subprocess.Popen(cmd, stdout=subprocess.PIPE, p = subprocess.Popen(cmd, stdout=subprocess.PIPE,
stderr=subprocess.PIPE, env=env) stderr=subprocess.PIPE, env=env, cwd=cwd)
out, err = p.communicate() out, err = p.communicate()
return p.returncode, out, err return p.returncode, out, err
class hgcommand(object): class hgcommand(object):
def __init__(self, cmd, env): def __init__(self, cmd, env):
self.cmd = cmd self.cmd = cmd
self.env = env self.env = env
log.info("done updating hg.exe's manifest") log.info("done updating hg.exe's manifest")
os.remove(manfname) os.remove(manfname)
@property @property
def hgexepath(self): def hgexepath(self):
dir = os.path.dirname(self.get_ext_fullpath('dummy')) dir = os.path.dirname(self.get_ext_fullpath('dummy'))
return os.path.join(self.build_temp, dir, 'hg.exe') return os.path.join(self.build_temp, dir, 'hg.exe')
class hgbuilddoc(Command):
description = 'build documentation'
user_options = [
('man', None, 'generate man pages'),
('html', None, 'generate html pages'),
]
def initialize_options(self):
self.man = None
self.html = None
def finalize_options(self):
# If --man or --html are set, only generate what we're told to.
# Otherwise generate everything.
have_subset = self.man is not None or self.html is not None
if have_subset:
self.man = True if self.man else False
self.html = True if self.html else False
else:
self.man = True
self.html = True
def run(self):
def normalizecrlf(p):
with open(p, 'rb') as fh:
orig = fh.read()
if b'\r\n' not in orig:
return
log.info('normalizing %s to LF line endings' % p)
with open(p, 'wb') as fh:
fh.write(orig.replace(b'\r\n', b'\n'))
def gentxt(root):
txt = 'doc/%s.txt' % root
log.info('generating %s' % txt)
res, out, err = runcmd(
[sys.executable, 'gendoc.py', root],
os.environ,
cwd='doc')
if res:
raise SystemExit('error running gendoc.py: %s' %
'\n'.join([out, err]))
with open(txt, 'wb') as fh:
fh.write(out)
def gengendoc(root):
gendoc = 'doc/%s.gendoc.txt' % root
log.info('generating %s' % gendoc)
res, out, err = runcmd(
[sys.executable, 'gendoc.py', '%s.gendoc' % root],
os.environ,
cwd='doc')
if res:
raise SystemExit('error running gendoc: %s' %
'\n'.join([out, err]))
with open(gendoc, 'wb') as fh:
fh.write(out)
def genman(root):
log.info('generating doc/%s' % root)
res, out, err = runcmd(
[sys.executable, 'runrst', 'hgmanpage', '--halt', 'warning',
'--strip-elements-with-class', 'htmlonly',
'%s.txt' % root, root],
os.environ,
cwd='doc')
if res:
raise SystemExit('error running runrst: %s' %
'\n'.join([out, err]))
normalizecrlf('doc/%s' % root)
def genhtml(root):
log.info('generating doc/%s.html' % root)
res, out, err = runcmd(
[sys.executable, 'runrst', 'html', '--halt', 'warning',
'--link-stylesheet', '--stylesheet-path', 'style.css',
'%s.txt' % root, '%s.html' % root],
os.environ,
cwd='doc')
if res:
raise SystemExit('error running runrst: %s' %
'\n'.join([out, err]))
normalizecrlf('doc/%s.html' % root)
# This logic is duplicated in doc/Makefile.
sources = {f for f in os.listdir('mercurial/help')
if re.search('[0-9]\.txt$', f)}
# common.txt is a one-off.
gentxt('common')
for source in sorted(sources):
assert source[-4:] == '.txt'
root = source[:-4]
gentxt(root)
gengendoc(root)
if self.man:
genman(root)
if self.html:
genhtml(root)
class hginstall(install): class hginstall(install):
user_options = install.user_options + [ user_options = install.user_options + [
('old-and-unmanageable', None, ('old-and-unmanageable', None,
'noop, present for eggless setuptools compat'), 'noop, present for eggless setuptools compat'),
('single-version-externally-managed', None, ('single-version-externally-managed', None,
'noop, present for eggless setuptools compat'), 'noop, present for eggless setuptools compat'),
] ]
'not known' % outfile) 'not known' % outfile)
continue continue
data = data.replace(b'@LIBDIR@', libdir.encode(libdir_escape)) data = data.replace(b'@LIBDIR@', libdir.encode(libdir_escape))
with open(outfile, 'wb') as fp: with open(outfile, 'wb') as fp:
fp.write(data) fp.write(data)
cmdclass = {'build': hgbuild, cmdclass = {'build': hgbuild,
'build_doc': hgbuilddoc,
'build_mo': hgbuildmo, 'build_mo': hgbuildmo,
'build_ext': hgbuildext, 'build_ext': hgbuildext,
'build_py': hgbuildpy, 'build_py': hgbuildpy,
'build_scripts': hgbuildscripts, 'build_scripts': hgbuildscripts,
'build_hgextindex': buildhgextindex, 'build_hgextindex': buildhgextindex,
'install': hginstall, 'install': hginstall,
'install_lib': hginstalllib, 'install_lib': hginstalllib,
'install_scripts': hginstallscripts, 'install_scripts': hginstallscripts,