diff options
| author | Martin Fischer <martin@push-f.com> | 2022-02-08 04:30:09 +0100 |
|---|---|---|
| committer | Martin Fischer <martin@push-f.com> | 2022-02-08 04:41:21 +0100 |
| commit | 489fe697cc12eb7cf3e12568546b4d133538ab6b (patch) | |
| tree | e503396fa582774fdb3bc211e62a04e18109a63d | |
| parent | 0d57be7ea30129000db5494e1a65b79c7618eed0 (diff) | |
create start page
| -rw-r--r-- | CONTRIBUTING.md | 18 | ||||
| -rw-r--r-- | README.md | 13 | ||||
| -rwxr-xr-x | pydoc.py | 24 | ||||
| -rw-r--r-- | templates/index.html | 25 |
4 files changed, 78 insertions, 2 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..3e25908 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,18 @@ +## How to contribute + +* You can give feedback and suggest packages to be included, + either by [email] or in the [#pydoc] IRC channel on [Libera.Chat]. + +* You can contribute to [pydoctor]. + +* You can contribute to the individual Python projects + to improve their [docstrings]. + +* If you want to support pydoc.dev by providing hosting, + [please get in touch][email]. + +[email]: mailto:martin@push-f.com +[#pydoc]: https://web.libera.chat/?channel=#pydoc +[Libera.Chat]: https://libera.chat/ +[pydoctor]: https://github.com/twisted/pydoctor +[docstrings]: https://www.python.org/dev/peps/pep-0257/ @@ -1,6 +1,15 @@ -# pydoc.dev - docs.rs for Python +# pydoc.dev - consistent API docs for Python -* powered by [pydoctor] +Looking at the API documentations of Python packages can be a bit disorienting +because they can look different from project to project (since different +projects use different [Sphinx] themes) and because the API documentation +often is not structured after the Python modules. +**pydoc.dev** strives to be for Python what [docs.rs] is for Rust. +It works by downloading the source files from the [Python Package Index], +the API documentation is then generated with [pydoctor]. +[Sphinx]: https://www.sphinx-doc.org/ +[docs.rs]: https://docs.rs/ +[Python Package Index]: https://pypi.org/ [pydoctor]: https://github.com/twisted/pydoctor @@ -8,6 +8,8 @@ import zipfile from pathlib import Path from typing import Dict, List +import jinja2 +import mistletoe import pkg_resources import pydoctor.driver import requests @@ -75,10 +77,13 @@ if __name__ == '__main__': # 1. fetch sources + package_infos = {} + for package_name in ( pkg_resources.resource_string(__name__, 'packages.txt').decode().splitlines() ): package = fetch_package_info(package_name) + package_infos[package_name] = package version = package['info']['version'] sourceid = f'{package_name}-{version}' @@ -189,3 +194,22 @@ if __name__ == '__main__': latest = dist / package_name / 'latest' latest.unlink(missing_ok=True) latest.symlink_to(version) + + # 4. create start page + env = jinja2.Environment(loader=jinja2.PackageLoader("pydoc"), autoescape=True) + + readme_html = mistletoe.markdown( + pkg_resources.resource_string(__name__, 'README.md').decode() + ) + contributing_html = mistletoe.markdown( + pkg_resources.resource_string(__name__, 'CONTRIBUTING.md').decode() + ) + + with open(dist / 'index.html', 'w') as f: + f.write( + env.get_template('index.html').render( + readme=readme_html, + contributing=contributing_html, + packages=package_infos.items(), + ) + ) diff --git a/templates/index.html b/templates/index.html new file mode 100644 index 0000000..d368271 --- /dev/null +++ b/templates/index.html @@ -0,0 +1,25 @@ +<!doctype html> +<html> + <head> + <title>pydoc.dev - consistent API docs for Python</title> + <link rel="stylesheet" href="https://unpkg.com/bamboo.css"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <style> + body {max-width: 80ch;} + </style> + </head> + <body> + {{ readme | safe }} + + <p>pydoc.dev is currently in early alpha and only hosts + documentation for {{ packages | length }} packages:</p> + + <ul style="columns: 200px;"> + {% for package_name, package in packages %} + <li><a href="/{{package_name}}/latest/" title="{{package.info.summary}}">{{package.info.name}}</a></li> + {% endfor %} + </ul> + + {{ contributing | safe }} + </body> +</html> |