rsticle 0.1.0

Treat source files as articles / narrative documentation
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

#{
"""
This is an example module.

This text should not appear in the narrative output,
however, it should appear in the pydoc output
"""
#}

#: .. highlight:: python
#: 
#: A Python Example
#: ================
#:
#: We're outputting ReStructuredText, whose directive require
#: that their content be indented by four spaces.
#: Therefore we use the following ``rsticle`` directive::
#: 
#:     #> ____
#> ____
#:
#: Read this as "dedent every code block, then add this number of spaces".
#: 
#: This file will showcase the following function::

def strlen(s: str) -> int:
    return len(s)

#: As you can see, we need to explicitly control indentation,
#: because ReStructuredText directives need to be indented by four spaces.
#:
#: The following blocks will retain their relative indentation
#: by explicitly adding the required amount.
#:
#: We define a function::

def some_fun():
    #> ________
    #:
    #: document it::
    #:
    """This function does stuff"""
    #:
    #: but it ultimately does nothing::
    #:
    pass  # The docstring lied!
#> ____

if __name__ == "__main__": #
    print("strlen:", strlen("some text")) #