https://github.com/marekjm/docs-formatter

Docs formatter
https://github.com/marekjm/docs-formatter

docs-generator documentation documentation-tool text-formatting

Last synced: about 1 month ago
JSON representation

Docs formatter

• Host: GitHub
• URL: https://github.com/marekjm/docs-formatter
• Owner: marekjm
• License: gpl-3.0
• Created: 2019-01-02T07:47:54.000Z (about 6 years ago)
• Default Branch: master
• Last Pushed: 2022-05-20T19:09:05.000Z (over 2 years ago)
• Last Synced: 2024-10-19T10:40:34.125Z (3 months ago)
• Topics: docs-generator, documentation, documentation-tool, text-formatting
• Language: Python
• Size: 66.4 KB
• Stars: 2
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.txt
  • License: LICENSE

Awesome Lists containing this project

• project-awesome - marekjm/docs-formatter - Docs formatter (Python)

README

        
                                 Docs formatter                                 

                                ----------------                                

                              OVERVIEW OF CONTENTS                              

1 _______________________________________________________________________ README

2 _____________________________________________________________________ Features

3 ______________________________________________________________________ License

--------------------------------------------------------------------------------

                               TABLE OF CONTENTS                                

1 _______________________________________________________________________ README

1.1 ..................................................................... Output

1.2 ...................................................................... Input

2 _____________________________________________________________________ Features

2.1 ......................................................... Lists vs "listeds"

2.2 ................................................. Function call tree example

2.3 ....................................................... Features not present

3 ______________________________________________________________________ License

--------------------------------------------------------------------------------

  [1] README {readme}

  Docs formatter - a text formatter for documentation.

  [1.1] Output {readme.output}

  It  produces  a  preformatted  text output suitable for viewing on the command

  line and HTML output suitable for the Web. The HTML output is preformatted and

  looks  exactly  like  the  plain  text  output  for the command line; the only

  difference is the presence of hyperlinks and basic colourisation.

  [1.2] Input {readme.input}

  It takes source in LaTeX-like notation as input.

  [2] Features {features}

  Features of the formatter include:

  - automatic generation of Table of Contents

  - arbitrarily nested sections to express the necessary hierarchy

  - automatic text reflow

  - lists of items

  - "listeds"  displaying all possible values of certain kind (e.g. instructions

    of an architecture, packet types in a protocol)

  - automatic formatting of function call trees

  - references (forward and backward)

  - file inclusion

  [2.1] Lists vs "listeds"

  Here is an example of a list:

  - hello

  - world

  - lorem

  - ipsum

  Lists  may  not be nested. Descriptions of a list item may be arbitrarily long

  and include line breaks.

  Here is an example of a "listed":

    hello      world      foo        bar        baz        lorem      

    ipsum      alpha      beta       gamma      delta      epsilon    

  [2.2] Function call tree example

  An example of a formatted function call tree:

  main()

  ↳ open("/etc/example.conf")

  ↳ do_stuff(fd)

    Descriptions  may  be  present  at  each  level  of  the  call stack and are

    automatically  indented  to  be  just below and slightly to the right of the

    function call they describe.

    ↳ some_function_with_long_name(

                                     and_a = "pretty long"

                                   , list_of = "arguments"

                                   , that_it_needs_to = receive

      )

      Calls  whose  list  of arguments would exceed column limit if printed on a

      single line are automatically broken and reformatted.

    ↳ exit(1)

  This  feature  is  quite primitive and limited, and is only able to describe a

  single  call  tree  with  no  conditional calls. Any conditional calls must be

  marked as such in description.

  [2.3] Features not present

  Some  features  are  omitted  from the code to keep the formatter simple. Most

  notable  omissions  include lack of support for arbitrary levels of nesting of

  different  constructs  (e.g.  lists),  and lack of support for custom layouts.

  [3] License

  The code is published under GNU GPL v3.