- Home
- Get it
- Docs
- Extend/Develop

# Source code for sphinx.builders.manpage

    # -*- coding: utf-8 -*-
    """
        sphinx.builders.manpage
        ~~~~~~~~~~~~~~~~~~~~~~~

        Manual pages builder.

        :copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
        :license: BSD, see LICENSE for details.
    """

    from os import path

    from six import string_types

    from docutils.io import FileOutput
    from docutils.frontend import OptionParser

    from sphinx import addnodes
    from sphinx.builders import Builder
    from sphinx.environment import NoUri
    from sphinx.util import logging
    from sphinx.util.nodes import inline_all_toctrees
    from sphinx.util.osutil import make_filename
    from sphinx.util.console import bold, darkgreen  # type: ignore
    from sphinx.writers.manpage import ManualPageWriter, ManualPageTranslator

    if False:
        # For type annotation
        from typing import Any, Dict, List, Set, Union  # NOQA
        from sphinx.application import Sphinx  # NOQA

    logger = logging.getLogger(__name__)

    class ManualPageBuilder(Builder):
        """
        Builds groff output in manual page format.
        """
        name = 'man'
        format = 'man'
        default_translator_class = ManualPageTranslator
        supported_image_types = []  # type: List[unicode]

        def init(self):
            # type: () -> None
            if not self.config.man_pages:
                logger.warning('no "man_pages" config value found; no manual pages '
                               'will be written')

        def get_outdated_docs(self):
            # type: () -> Union[unicode, List[unicode]]
            return 'all manpages'  # for now

        def get_target_uri(self, docname, typ=None):
            # type: (unicode, unicode) -> unicode
            if typ == 'token':
                return ''
            raise NoUri

        def write(self, *ignored):
            # type: (Any) -> None
            docwriter = ManualPageWriter(self)
            docsettings = OptionParser(
                defaults=self.env.settings,
                components=(docwriter,),
                read_config_files=True).get_default_values()

            logger.info(bold('writing... '), nonl=True)

            for info in self.config.man_pages:
                docname, name, description, authors, section = info
                if isinstance(authors, string_types):
                    if authors:
                        authors = [authors]
                    else:
                        authors = []

                targetname = '%s.%s' % (name, section)
                logger.info(darkgreen(targetname) + ' { ', nonl=True)
                destination = FileOutput(
                    destination_path=path.join(self.outdir, targetname),
                    encoding='utf-8')

                tree = self.env.get_doctree(docname)
                docnames = set()  # type: Set[unicode]
                largetree = inline_all_toctrees(self, docnames, docname, tree,
                                                darkgreen, [docname])
                logger.info('} ', nonl=True)
                self.env.resolve_references(largetree, docname, self)
                # remove pending_xref nodes
                for pendingnode in largetree.traverse(addnodes.pending_xref):
                    pendingnode.replace_self(pendingnode.children)

                largetree.settings = docsettings
                largetree.settings.title = name
                largetree.settings.subtitle = description
                largetree.settings.authors = authors
                largetree.settings.section = section

                docwriter.write(largetree, destination)
            logger.info('')

        def finish(self):
            # type: () -> None
            pass

    def setup(app):
        # type: (Sphinx) -> Dict[unicode, Any]
        app.add_builder(ManualPageBuilder)

        app.add_config_value('man_pages',
                             lambda self: [(self.master_doc, make_filename(self.project).lower(),
                                            '%s %s' % (self.project, self.release), [], 1)],
                             None)
        app.add_config_value('man_show_urls', False, None)

        return {
            'version': 'builtin',
            'parallel_read_safe': True,
            'parallel_write_safe': True,
        }