Generate docs

[chuckwondo]

@francium, I know you have an old PR for this (#7), but thought I would make a corresponding issue because I am attempting to create a new PR (per your suggestion in #7), but I am finding the following anomaly with lazydocs: it doesn't deal with REPL syntax properly.

In particular, here is a problematic part of a docstring from the is_some function (and similarly for is_nothing):

    Usage:
    >>> r: Maybe[int, str] = get_a_maybe()
    >>> if is_some(r):
    >>>     r   # r is of type Some[int]
    >>> elif is_nothing(r):
    >>>     r   # r is of type Nothing[str]

Unfortunately, the generated HTML renders as follows:

Usage: r: Maybe[int, str] = get_a_maybe() if is_some(r): r # r is of type Some[int] elif is_nothing(r): r # r is of type Nothing[str]

This sort of makes sense in terms of pure translation of markdown to HTML because there are no intervening blank lines, so all of the lines are interpreted to be part of the same "paragraph," so each intervening newline is replaced with a single blank, and we end up with all of the "code" joined onto a single line.

Sadly, as far as I can tell, there is no way to completely correct this to allow correct rendering of REPL prompts, which is also sad because that eliminates the possibility of including doctest tests and having them rendered correctly in the generated docs.

For starters, I added a blank line after "Usage:" and surrounded the REPL lines in a plain code fence, like so:

    Usage:

    ```plain
    >>> r: Maybe[int, str] = get_a_maybe()
    >>> if is_some(r):
    >>>     r   # r is of type Some[int]
    >>> elif is_nothing(r):
    >>>     r   # r is of type Nothing[str]
    ```

This produced an even worse rendering:

Usage:

``` r: Maybe[int, str] = get_a_maybe()``` ``` if is_some(r):```
```     r   # r is of type Some[int]``` ``` elif is_nothing(r):```
```     r   # r is of type Nothing[str]``` ```



---

<a href="https://github.com/rustedpy/maybe/blob/main/src/maybe/maybe.py#L299"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>

## <kbd>function</kbd> `is_nothing`

```python
is_nothing(maybe: 'Maybe[T]') → TypeGuard[Nothing]

Of course, I realize that the REPL syntax should actually be corrected as follows (notice, the ... in place of some of the >>>), if it is to be a true REPL representation:

    Usage:

    ```plain
    >>> r: Maybe[int, str] = get_a_maybe()
    >>> if is_some(r):
    ...     r   # r is of type Some[int]
    ... elif is_nothing(r):
    ...     r   # r is of type Nothing[str]
    ```

Unfortunately, that does not render any better, nor did I really expect it to, since ... vs. >>> is not the source of the rendering problem.

The "fix" is to simply remove the REPL prompts, and make it a regular code fence, like so:

    Usage:

    ```python
    r: Maybe[int, str] = get_a_maybe()
    if is_some(r):
        r   # r is of type Some[int]
    elif is_nothing(r):
        r   # r is of type Nothing[str]
    ```

This renders like so:

Usage:

r: Maybe[int, str] = get_a_maybe()
if is_some(r):
    r   # r is of type Some[int]
elif is_nothing(r):
    r   # r is of type Nothing[str]

Are you okay with making this type of adjustment to the docstrings for both is_some and is_nothing?

[chuckwondo]

Aha! If I add some extra indentation within the code fence, it seems to do the trick.

So this:

    Usage:

    ```
        >>> r: Maybe[int, str] = get_a_maybe()
        >>> if is_some(r):
        ...     r   # r is of type Some[int]
        ... elif is_nothing(r):
        ...     r   # r is of type Nothing[str]
    ```

Renders like so:

Usage:

     >>> r: Maybe[int, str] = get_a_maybe()
     >>> if is_some(r):
     ...     r   # r is of type Some[int]
     ... elif is_nothing(r):
     ...     r   # r is of type Nothing[str]

It seems that lazydocs simply needs at least one space indent from the triple-backticks in order to not wrap the lines, so I'm going to make that slight adjustment to fix the rendering.

[chuckwondo]

Related to this, I submitted a bug report and a feature request to lazydocs:

• Incorrect markdown generated for fenced code blocks containing doctest tests ml-tooling/lazydocs#79
• Support indented (unfenced) code blocks ml-tooling/lazydocs#80