diff --git a/README.md b/README.md index 1f0476f..dee3dbe 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,34 @@ It is still in early development, this README will be updated when I get to depl - The UI is pure HTML/CSS - Except a tiny bit of hand-written JS in the note composer to insert emoji - IndieWeb citizen - - Microformats everywhere - - Webmentions support - - RSS/Atom/JSON feed + - [IndieAuth](https://www.w3.org/TR/indieauth/) support (OAuth2 extension) + - [Microformats](http://microformats.org/wiki/Main_Page) everywhere + - Sends and processes [Webmentions](https://www.w3.org/TR/webmention/) + - RSS/Atom/[JSON](https://www.jsonfeed.org/) feed + - Easy to backup + - Everything is stored in the `data/` directory: config, uploads, secrets and the SQLite database. + +## Getting started + +Check out the [online documentation](https://docs.microblog.pub). + +## Credits + + - Emoji from [Twemoji](https://twemoji.twitter.com/) + - Awesome custom goose emoji from [@pamela@bsd.network](https://bsd.network/@pamela) + + +## Contributing + +All the development takes place on [sourcehut](https://sr.ht/~tsileo/microblog.pub/), GitHub is only used as a mirror: + + - [Project](https://sr.ht/~tsileo/microblog.pub/) + - [Issue tracker](https://todo.sr.ht/~tsileo/microblog.pub) + - [Mailing list](https://sr.ht/~tsileo/microblog.pub/lists) + +Contributions are welcomed, check out the [documentation](https://docs.microblog.pub) for more details. + + +## License + +The project is licensed under the GNU AGPL v3 LICENSE (see the LICENSE file). diff --git a/docs/developer_guide.md b/docs/developer_guide.md new file mode 100644 index 0000000..584707b --- /dev/null +++ b/docs/developer_guide.md @@ -0,0 +1,59 @@ +# Developer's guide + +This guide assume you have some knoweldge of [ActivityPub](https://activitypub.rocks/). + +[TOC] + +## Architecture + +Microblog.pub is a "modern" Python application with "old-school" server-rendered templates. + + - [Poetry](https://python-poetry.org/) is used for dependency management. + - Most of the code is asynchronous, using [asyncio](https://docs.python.org/3/library/asyncio.html). + - SQLite3 is the default database. + +The server has 2 components: + + - The web server (powered by [FastAPI](https://fastapi.tiangolo.com/) and [Jinja2](https://jinja.palletsprojects.com/en/3.1.x/) templates) + - An additional process that takes care of sending "outgoing actities" + +## Tasks + +The project uses [Invoke](https://www.pyinvoke.org/) to manage tasks (a Python powered Makefile). + +You can find the tasks definition in `tasks.py` and list the tasks using: + +```bash +inv -l +``` + +### Media storage + +The uploads are stored in the `data/` directory, using a simple content-addressed storage (file contents hash is the name of the store BLOB). +Files metadata are stored in the database. + +## Installation + +Running a local version requires: + + - Python 3.10+ + - SQLite 3.35+ + +You can follow the [Python developer version of the install instructions](https://docs.microblog.pub/installing.html#python-developer-edition). + +## Documentation + +The documention is managed as Markdown files in `docs/` and the online documentation is built using a homegrown Python script (`scripts/build_docs.py`). + +You can build the documentation locally by running: + +```bash +inv build-docs +``` + +And check out the result by starting a static server using Python standard library: + +```bash +cd docs/dist +python -m http.server 8001 +``` diff --git a/docs/templates/layout.html b/docs/templates/layout.html index 4def13d..2bda71d 100644 --- a/docs/templates/layout.html +++ b/docs/templates/layout.html @@ -63,12 +63,16 @@ nav a:hover, main a:hover, header p a:hover { max-width: 960px; margin: 50px auto; } -code { +pre code { padding: 10px; overflow: auto; display: block; font-family: monospace; } +footer { + margin-top: 50px; + color: #555; +} @@ -83,11 +87,11 @@ code { @@ -95,6 +99,9 @@ code { {{ content | safe }} + diff --git a/docs/user_guide.md b/docs/user_guide.md index 6569fac..f132024 100644 --- a/docs/user_guide.md +++ b/docs/user_guide.md @@ -1,5 +1,14 @@ -# User guide +# User's guide [TOC] -TODO +## Backup and restore + +All the data generated by the server is located in the `data/` directory: + + - The server configuration (in `profile.toml`) + - The server secrets + - The SQLite3 database + - The uploaded media + +Restoring is as easy as adding your backed up `data/` directory into a fresh deployment. diff --git a/scripts/build_docs.py b/scripts/build_docs.py index b77b7c8..9174a20 100644 --- a/scripts/build_docs.py +++ b/scripts/build_docs.py @@ -6,6 +6,7 @@ from jinja2 import FileSystemLoader from jinja2 import select_autoescape from markdown import markdown +from app.database import now from app.config import VERSION @@ -26,6 +27,8 @@ def main() -> None: shutil.rmtree("docs/dist/static", ignore_errors=True) shutil.copytree("docs/static", "docs/dist/static") + last_updated = now().isoformat() + readme = Path("README.md") template.stream( content=markdownify(readme.read_text().removeprefix("# microblog.pub")), @@ -38,6 +41,7 @@ def main() -> None: content=markdownify(install.read_text()), version=VERSION, path="/installing.html", + last_updated=last_updated, ).dump("docs/dist/installing.html") user_guide = Path("docs/user_guide.md") @@ -45,8 +49,17 @@ def main() -> None: content=markdownify(user_guide.read_text()), version=VERSION, path="/user_guide.html", + last_updated=last_updated, ).dump("docs/dist/user_guide.html") + developer_guide = Path("docs/developer_guide.md") + template.stream( + content=markdownify(developer_guide.read_text()), + version=VERSION, + path="/developer_guide.html", + last_updated=last_updated, + ).dump("docs/dist/developer_guide.html") + if __name__ == "__main__": main()