Handsdown

Features

Add Read the Docs support

Added a new CLI argument `--external` - replacement for removed `--gh-pages` argument, because now it handles both [Read the Docs](https://readthedocs.org) and [GitHub Pages](https://pages.github.com).

The output produced by `handsdown` is now compatible with `mkdocs` format. That means that you can generate HTML from `handsdown` output:

bash
build documentation with absolute links to GitHub repo source files
and generate config files for mkdocs, Read the Docs and GitHub Pages
handsdown --external `git config --get remote.origin.url`

build HTML to `site` directory
mkdocs build


Signature builder improvements

- Now you can see decorators in a function signature
- Comment-style type annotation parsing now produces correct result for partially annotated functions
- Faster source code processing

Here is an example of a new annotation

python
property
def title() -> Text:

title.setter
def title(title: Text) -> None:


Bugfixes

- Only enable type checking for a primary imported module and disable for other
- Use full config for `GitHub Pages`
- Make signature compatible with `GitHub` highlighter
- Fix installation from `.tar.gz`

Other changes

- Remove `--gh-pages` CLI argument
- Modules list moved to `MODULES.md`
- Add support for custom content in Modules list file
- Use project name as an index title in submodule ToC
- Add `--version` CLI argument
- Add version info installed package

Bugfixes

- [x] Fix crash on getting source code line from non-readable files
- [x] Skip directories starting with `.` (Python eggs could be stored in a project root)
- [x] Fix circular imports by enabling `typing.TYPE_CHECKING` only for the first file
- [x] Support `HTTPS` protocol in `git config --get remote.origin.url`

Highlights

Going stable

`handsdown` is still in alpha, but it already has all planned features and plenty of supported Python versions. This is the first production-ready release.

Python 3.5 and 3.6 support

Yes, the source code became uglier, but it works on all popular Python versions now! Thanks to developers of [Future f-strings](https://pypi.org/project/future-fstrings/) package, `f-strings` are still there in exchange for one extra dependency. Data classes are gone though and I will miss them. `py36` delivers full-featured `handsdown` experience while `py35` does not render complex type annotations, e.g. `List[Text]` becomes `List`.

Python 2.7 support

This was huge. It started with comment-style type annotations and ended up with a full object signature rewrite as `py27` does not have many useful functions from `inspect` module.

Comment-style type annotations

Of course, this comes with `py27` support. Say hello to ` type: (Text, Text) -> None` comments under your functions. Do you use them? Well, they are fully supported and have no disadvantages compared to `py37`-style annotations.

Thanks to developers of [pytypes](https://github.com/Stewori/pytypes), I got an idea of how type hints should really be implemented in Python. However, I did not add this project to dependencies, I just used it for inspiration.

Features

- [x] Python 2.7 support
- [x] Python 3.5 support
- [x] Python 3.6 support
- [x] Python 3.8 support
- [x] PyPy 7.2.0 support
- [x] Support comment-style type annotations

Bugfixes

- [x] Render dynamic default values correctly
- [x] Do not render `args` and `kwargs` inherited from `object`
- [x] Fix anchor links for GitHub Pages
- [x] Fix duplicate auto-generated subtitles
- [x] Fix crash on nameless function (hello Django `operator.attrgetter`)

Bugfixes

- [x] Regenerate `README.md` Table of Contents to avoid dead links
- [x] Link generation fixes for `GitHub Pages`
- [x] Exclude `__pycache__` from sources list

Features

- [x] Support doctest strings: `>>> print('finally')`
- [x] Support code blocks starting after a section title, e. g. `Examples::`
- [x] Add properties documentation
- [x] Support output folder outside of root path
- [x] Add support for [GitHub Pages](https://pages.github.com/)

Changes

- [x] Use nested docs structure
- [x] Add `--cleanup` CLI argument
- [x] Add `--gh-pages` CLI argument

Bugfixes

- [x] Fix local modules discovery for installed packages
- [x] Fix parsing of Google-style optional arguments
- [x] Fix module objects listing before docstring lines
- [x] Fix lowercase section names for PEP 257
- [x] Fix wrong indentation in sections with code blocks
- [x] Fix wrong indentation for tilde code blocks
- [x] Fix Sphinx-style titles breaking output
- [x] Fix links discovery in attached `README.md`

Goals reached

- All features from [Flask](https://github.com/pallets/flask) docs are now supported!
- Finally, submodules tree looks exactly like it should
- No need to use a full import path to reference an imported object

Features

- [x] Show child modules in ToC
- [x] RST: add code blocks support
- [x] RST: add expressions support
- [x] RST: support double quotes for link lookup
- [x] Add anchor to module links for easier navigation on GitHub
- [x] Add subtitle support to generated docs
- [x] New link lookup for related objects
- [x] Add `--safe` CLI argument to ignore all errors during import

Bugfixes

- [x] Add missing top-level module to breadcrumbs
- [x] Fix breadcrumbs generation for top-level modules
- [x] Fix underscores in titles and ToC

Other changes

- [x] Remove `Modules` section
- [x] Move breadcrumbs to ToC
- [x] Add RST docstring format example
- [x] Clean `auto-generated` subtitles
- [x] Use project name as a to doc index title