Tweak documentation

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
+    - [IndieAuth](https://www.w3.org/TR/indieauth/) support (OAuth2 extension)
-    - Webmentions support
+    - [Microformats](http://microformats.org/wiki/Main_Page) everywhere
-    - RSS/Atom/JSON feed
+    - 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).

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
+```

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;
+}
 </style>
 <link rel="stylesheet" href="static/codehilite.css" type="text/css" />
 </head>
@@ -83,11 +87,11 @@ code {
         <ul>
             <li><a href="/"{% if path == "/" %} class="active"{% endif %}>Home</a>
             <li><a href="/installing.html"{% if path == "/installing.html" %} class="active"{% endif %}>Installing</a>
-            <li><a href="/user_guide.html"{% if path == "/user_guide.html" %} class="active"{% endif %}>User guide</a>
+            <li><a href="/user_guide.html"{% if path == "/user_guide.html" %} class="active"{% endif %}>User's guide</a>
+            <li><a href="/developer_guide.html"{% if path == "/developer_guide.html" %} class="active"{% endif %}>Developer's guide</a>
             <li><a href="https://sr.ht/~tsileo/microblog.pub/">Source code</a>
             <li><a href="https://todo.sr.ht/~tsileo/microblog.pub">Bug tracker</a>
             <li><a href="https://sr.ht/~tsileo/microblog.pub/lists">Mailing list</a>
-            <li><code>{{ version }}</code></li>
         </ul>
     </nav>
 
@@ -95,6 +99,9 @@ code {
     {{ content | safe }}
     </main>
 
+    <footer>
+        <p>Last updated {{ last_updated }} for <code>{{ version }}</p>
+    </footer>
 </div>
 </body>
 </html>

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.

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()