Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

Documentation ignores the \b characters in docstrings

See original GitHub issue

As is documented in click here, the docstrings for click commands are expected to contain \b characters before a paragraph which should not be made to wrap.

This allows better formatting of docstrings in the help output, without this it is impossible to make any kind of formatting of the help such as point form lists which describe the meaning of each click.Choice() option.

This works well for click’s help output, but is also broken for the click-man generated man pages, and for sphinx-click generated html (although the man pages are slightly less broken than the html).

See this example of the breakage and compare with the corresponding help output below:

Usage: bst show [OPTIONS] TARGET

  Show elements in the pipeline

  By default this will only show the specified element, use the --deps
  option to show an entire pipeline.

  The --format option controls what should be printed for each element,
  the following symbols can be used in the format string:

      %{name}     The element name
      %{key}      The abbreviated cache key (if all sources are consistent)
      %{full-key} The full cache key (if all sources are consistent)
      %{state}    cached, buildable, waiting or inconsistent
      %{config}   The element configuration
      %{vars}     Variable configuration
      %{env}      Environment settings
      %{public}   Public domain data

  The value of the %{symbol} without the leading '%' character is understood
  as a pythonic formatting string, so python formatting features apply,

      build-stream show target.bst --format \
          'Name: %{name: ^20} Key: %{key: ^8} State: %{state}'

  If you want to use a newline in a format string in bash, use the '$'

      build-stream show target.bst --format \
          $'---------- %{name} ----------\n%{vars}'

  -d, --deps [all|build|run]  Optionally specify a dependency scope to show
  --order [stage|alpha]       Staging or alphabetic ordering of dependencies
  -f, --format FORMAT         Format string for each element
  -a, --arch TEXT             The target architecture (default: x86_64)
  --variant TEXT              A variant of the specified target
  --help                      Show this message and exit.

Issue Analytics

  • State:closed
  • Created 6 years ago
  • Reactions:1
  • Comments:9 (4 by maintainers)

github_iconTop GitHub Comments

gtristancommented, Aug 29, 2017

@stephenfin I guess I just went on a tangent on what might be the ideal solution…

So, basically I have three outputs of my doc strings:

  • application --help output
  • man pages generated with the click_man thing
  • documentation generated with sphinx-click

With the application help output, I can do some alignments and tables and stuff, like:

    Values for the --frobtype argument
        foo        Frob it with foo
        bar        Bar it from any frobbing
        baz        Frob it baz

So I can create aligned output in the additional text I write in the documentation body and am not limited to the alignment provided by argument options; but in html this alignment is lost because of lack of monospace fonts.

I think it makes sense with the current approach to force monospace fonts in the rendered docs, otherwise there is no way to use any alignment in your help text.

Looking at the reverse approach

With man pages we have more freedom of expression than with help output, and with HTML we have even more freedom.

The current approach with click is to write a very, very simple format for help output (the format is just text with a special meaning of the \b character); and then use that same format to generate man pages and html documentation.

Things would make more sense the other way around:

  • Click command docstrings should support markdown
  • Click itself should honor the markdown on a best effort basis when printing --help output
  • The man pages can do a better job of honoring the markdown
  • The html can do an even better job of honoring the markdown

Just saying, this would be a much nicer experience 😃

stephenfincommented, Dec 3, 2018

Fixed in the above commit.

Read more comments on GitHub >

github_iconTop Results From Across the Web

Python Docstrings (With Examples) - Programiz
In this tutorial, we will learn about Python docstrings. More specifically, we will learn how and ... They are completely ignored by the...
Read more >
How to Document Your Code - pydoctor documentation
Since docstrings are Python strings, escape sequences such as \n will be parsed as if the corresponding character—for example a newline—occurred at the ......
Read more >
Multi-line description of a parameter description in python ...
Personally, I prefer to align all additional lines to the first description line of that parameter. Note, that reST will also ignore new...
Read more >
Python: Docstrings - STechies
A docstring in Python is a way to provide an explanation along with functions, modules, and classes. They are documentation strings that are...
Read more >
Documentation in Comments | Individual Software Process
The docstring must be the first thing inside a function and use a multi-line comment (“””). Same rule for class docstrings. The first...
Read more >

github_iconTop Related Medium Post

No results found

github_iconTop Related StackOverflow Question

No results found

github_iconTroubleshoot Live Code

Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free

github_iconTop Related Reddit Thread

No results found

github_iconTop Related Hackernoon Post

No results found

github_iconTop Related Tweet

No results found

github_iconTop Related Post

No results found

github_iconTop Related Hashnode Post

No results found