Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.debian.maint.python > #9661

Re: building manpages via setup.py

Show key headers only | View raw

On 01/08/17 15:15, PICCA Frederic-Emmanuel wrote:
> Hello,
> 
> I am working on the pyfai package.
> This pacakge contain one module with extensions (the important point)
> 
> The new upstream version 0.14.0 provide a build_man target via the setup.py
> 
> So in ordert to generate the doc I need to do
> 
> python setup.py build_man
> 
> Now if I look at this target, I can find this code
> 
> -----
> 
> class BuildMan(Command):
>      """Command to build man pages"""
>      user_options = []
> 
>      def initialize_options(self):
>          pass
> 
>      def finalize_options(self):
>          pass
> 
>      def entry_points_iterator(self):
>          """Iterate other entry points available on the project."""
>          entry_points = self.distribution.entry_points
>          console_scripts = entry_points.get('console_scripts', [])
>          gui_scripts = entry_points.get('gui_scripts', [])
>          scripts = []
>          scripts.extend(console_scripts)
>          scripts.extend(gui_scripts)
>          for script in scripts:
>              elements = script.split("=")
>              target_name = elements[0].strip()
>              elements = elements[1].split(":")
>              module_name = elements[0].strip()
>              function_name = elements[1].strip()
>              yield target_name, module_name, function_name
> 
>      def run(self):
>          build = self.get_finalized_command('build')
>          path = sys.path
>          path.insert(0, os.path.abspath(build.build_lib))
> 
>          env = dict((str(k), str(v)) for k, v in os.environ.items())
>          env["PYTHONPATH"] = os.pathsep.join(path)
> 
>          import subprocess
> 
>          status = subprocess.call(["mkdir", "-p", "build/man"])
>          if status != 0:
>              raise RuntimeError("Fail to create build/man directory")
> 
>          import tempfile
>          import stat
>          script_name = None
> 
>          entry_points = self.entry_points_iterator()
>          for target_name, module_name, function_name in entry_points:
>              logger.info("Build man for entry-point target '%s'" % target_name)
>              # help2man expect a single executable file to extract the help
>              # we create it, execute it, and delete it at the end
> 
>              py3 = sys.version_info >= (3, 0)
>              try:
>                  # create a launcher using the right python interpreter
>                  script_fid, script_name = tempfile.mkstemp(prefix="%s_" % target_name, text=True)
>                  script = os.fdopen(script_fid, 'wt')
>                  script.write("#!%s\n" % sys.executable)
>                  script.write("import %s as app\n" % module_name)
>                  script.write("app.%s()\n" % function_name)
>                  script.close()
>                  # make it executable
>                  mode = os.stat(script_name).st_mode
>                  os.chmod(script_name, mode + stat.S_IEXEC)
> 
>                  # execute help2man
>                  man_file = "build/man/%s.1" % target_name
>                  command_line = ["help2man", script_name, "-o", man_file]
>                  if not py3:
>                      # Before Python 3.4, ArgParser --version was using
>                      # stderr to print the version
>                      command_line.append("--no-discard-stderr")
> 
>                  p = subprocess.Popen(command_line, env=env)
>                  status = p.wait()
>                  if status != 0:
>                      raise RuntimeError("Fail to generate '%s' man documentation" % target_name)
>              finally:
>                  # clean up the script
>                  if script_name is not None:
>                      os.remove(script_name)
> -----
> 
> 
> As you can see this create a launch script for each entry point found in the setup.py and run help2man on it.
> 
> For now I would like to use this setup.py without modification.
> 
> So what should I do to run
> 
> python setup.py build_man with the options provided by pybuild during the normal build in order to let the  generated script find the pyFAI modules and its extensions ?

Simplest I can think of would be to build the extensions inplace 
followed by the call to build_man. Something like:

override_dh_auto_build:
	dh_auto_build
	python3 setup.py build_ext --inplace
	python3 setup.py build_man

I left the http_proxy exports and nodoc guards out for clarity.

> Second questions what is the right way to generate the man pages for a python application ?

Usually via Sphinx if the upstream documentation uses it. Regardless of 
the stack, `help2man` is often considered the poor man choice for 
generating manpages.

Let me know if you'd like me to have a look :-)

Ghis

Back to linux.debian.maint.python | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

building manpages via setup.py PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr> - 2017-08-01 16:50 +0200
  Re: building manpages via setup.py Ghislain Vaillant <ghisvail@gmail.com> - 2017-08-01 17:00 +0200
    RE:building manpages via setup.py PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr> - 2017-08-01 17:50 +0200
  Re: building manpages via setup.py Piotr Ożarowski <piotr@debian.org> - 2017-08-01 17:40 +0200
    RE:building manpages via setup.py PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr> - 2017-08-02 09:20 +0200
      Re: building manpages via setup.py Piotr Ożarowski <piotr@debian.org> - 2017-08-02 09:30 +0200
        Re: building manpages via setup.py Piotr Ożarowski <piotr@debian.org> - 2017-08-02 09:50 +0200
          Re: building manpages via setup.py Ghislain Vaillant <ghisvail@gmail.com> - 2017-08-02 09:50 +0200
            Re: building manpages via setup.py Ghislain Vaillant <ghisvail@gmail.com> - 2017-08-02 10:20 +0200
              RE:building manpages via setup.py PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr> - 2017-08-02 10:40 +0200
                Re: building manpages via setup.py Ghislain Vaillant <ghisvail@gmail.com> - 2017-08-02 10:40 +0200
                RE:building manpages via setup.py PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr> - 2017-08-02 11:20 +0200
                Re: building manpages via setup.py Ghislain Vaillant <ghisvail@gmail.com> - 2017-08-02 11:30 +0200
                RE:building manpages via setup.py PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr> - 2017-08-02 12:10 +0200
                Re: building manpages via setup.py Ghislain Vaillant <ghisvail@gmail.com> - 2017-08-02 12:50 +0200
                RE:building manpages via setup.py PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr> - 2017-08-02 14:30 +0200
            RE:building manpages via setup.py PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr> - 2017-08-02 10:30 +0200
        RE:building manpages via setup.py PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr> - 2017-08-02 09:50 +0200
        RE:building manpages via setup.py PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr> - 2017-08-03 12:20 +0200
          RE:building manpages via setup.py PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr> - 2017-08-03 15:50 +0200
            RE:building manpages via setup.py PICCA Frederic-Emmanuel <frederic-emmanuel.picca@synchrotron-soleil.fr> - 2017-08-03 16:20 +0200

csiph-web