Tweak documentation

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.