Tweak documentation

This commit is contained in:
Thomas Sileo 2022-07-11 22:01:37 +02:00
parent 12c328a0b3
commit 261417cab3
5 changed files with 124 additions and 8 deletions

View file

@ -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 - The UI is pure HTML/CSS
- Except a tiny bit of hand-written JS in the note composer to insert emoji - Except a tiny bit of hand-written JS in the note composer to insert emoji
- IndieWeb citizen - 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).

59
docs/developer_guide.md Normal file
View file

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

View file

@ -63,12 +63,16 @@ nav a:hover, main a:hover, header p a:hover {
max-width: 960px; max-width: 960px;
margin: 50px auto; margin: 50px auto;
} }
code { pre code {
padding: 10px; padding: 10px;
overflow: auto; overflow: auto;
display: block; display: block;
font-family: monospace; font-family: monospace;
} }
footer {
margin-top: 50px;
color: #555;
}
</style> </style>
<link rel="stylesheet" href="static/codehilite.css" type="text/css" /> <link rel="stylesheet" href="static/codehilite.css" type="text/css" />
</head> </head>
@ -83,11 +87,11 @@ code {
<ul> <ul>
<li><a href="/"{% if path == "/" %} class="active"{% endif %}>Home</a> <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="/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://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://todo.sr.ht/~tsileo/microblog.pub">Bug tracker</a>
<li><a href="https://sr.ht/~tsileo/microblog.pub/lists">Mailing list</a> <li><a href="https://sr.ht/~tsileo/microblog.pub/lists">Mailing list</a>
<li><code>{{ version }}</code></li>
</ul> </ul>
</nav> </nav>
@ -95,6 +99,9 @@ code {
{{ content | safe }} {{ content | safe }}
</main> </main>
<footer>
<p>Last updated {{ last_updated }} for <code>{{ version }}</p>
</footer>
</div> </div>
</body> </body>
</html> </html>

View file

@ -1,5 +1,14 @@
# User guide # User's guide
[TOC] [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.

View file

@ -6,6 +6,7 @@ from jinja2 import FileSystemLoader
from jinja2 import select_autoescape from jinja2 import select_autoescape
from markdown import markdown from markdown import markdown
from app.database import now
from app.config import VERSION from app.config import VERSION
@ -26,6 +27,8 @@ def main() -> None:
shutil.rmtree("docs/dist/static", ignore_errors=True) shutil.rmtree("docs/dist/static", ignore_errors=True)
shutil.copytree("docs/static", "docs/dist/static") shutil.copytree("docs/static", "docs/dist/static")
last_updated = now().isoformat()
readme = Path("README.md") readme = Path("README.md")
template.stream( template.stream(
content=markdownify(readme.read_text().removeprefix("# microblog.pub")), content=markdownify(readme.read_text().removeprefix("# microblog.pub")),
@ -38,6 +41,7 @@ def main() -> None:
content=markdownify(install.read_text()), content=markdownify(install.read_text()),
version=VERSION, version=VERSION,
path="/installing.html", path="/installing.html",
last_updated=last_updated,
).dump("docs/dist/installing.html") ).dump("docs/dist/installing.html")
user_guide = Path("docs/user_guide.md") user_guide = Path("docs/user_guide.md")
@ -45,8 +49,17 @@ def main() -> None:
content=markdownify(user_guide.read_text()), content=markdownify(user_guide.read_text()),
version=VERSION, version=VERSION,
path="/user_guide.html", path="/user_guide.html",
last_updated=last_updated,
).dump("docs/dist/user_guide.html") ).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__": if __name__ == "__main__":
main() main()