Read your RSS feeds & save other articles
Legadilo is a project to help you subscribe to RSS feeds, save articles and organize them easily with tags and full customizable reading lists! It’s written with the Django web framework, the boostrap 5 frontend toolkit and with enhancements given by htmx.
It’s opensource under the GNU AGPLv3 and is designed to be self-hostable, so you can run your own instance.
Your ideas, contributions and feedback are welcomed! You can also check the official instance to start using it more easily (you will be able to export and import your data in any instance)! If you contribute, don’t forget to add yourselves to the CONTRIBUTORS.txt
file.
npm install
to install our few JS deps.docker compose -f local.yml up
You can rely on the devcontainer.json
file to start the project and develop teh project inside a container. This way, you don’t need to install anything on your machine to make it work (besides docker). VSCode should propose you continue in a container the first time you open the project and will take care of the rest for you. See here for more.
You will have to start Django with the provided run target.
By default, everything is set up to develop locally with Pycharm. So you will need docker (for the database), poetry, Python 3.12 and nodeJS 20+ installed for this to work. Django will be started automatically. On the first run, you must run npm install
to install a few JS deps.
You should also be able to use devcontainers but the support is more recent and isn’t as good as in VSCode according to my tests. See here for more.
legadilo/
.config/
.docs/
It’s built with sphinx and mostly written in MyST (MyST is a rich and extensible flavor of Markdown meant for technical documentation and publishing).devops/
local.yml
for local development and production.yml
for running the project in production.manage.py
is Django commands’ main entry point.locale/
will be used to translate the project. Currently, we only mark the strings for translation..github/
is used to configure dependabot and the CI..app-template/
is used by Django to create a new app..decontainer/
, .idea/
, .vscode/
and .editorconfig
are editors configuration..eslintrc.json
, prettierrc.json
and .stylelintrc.json
contains the JS/CSS linters and formatters configurations.pyproject.toml
defines the Python dependencies and is used to configure Python linting tools.poetry.lock
and package-lock.json
are used to lock the dependencies.All these commands must be run at the root of the project!
python manage.py runserver
python manage.py makemigrations
python manage.py migrate
python manage.py createsuperuser
In development, it is often nice to be able to see emails that are being sent from your application. For that reason local SMTP server Mailpit with a web interface is available as docker container.
Container mailpit will start automatically when you will run all docker containers. Please check cookiecutter-django Docker documentation for more details how to start all containers.
With Mailpit running, to view messages that are sent by your application, open your browser and go to http://127.0.0.1:8025
To create a superuser account, use this command:
$ python manage.py createsuperuser
For convenience, you can keep your normal user logged in on Chrome and your superuser logged in on Firefox (or similar), so that you can see how the site behaves for both kinds of users.
All code should be tested and type annotated. We use pytest as our test runner and mypy as our type checker. We use ruff to lint and format our code. You can:
pre-commit run mypy -a
pytest
(note: both VSCode and Pycharm should be able to run the tests natively)pre-commit run ruff -a
(this should be done automatically on save)pre-commit run ruff-format
(this should be done automatically on save)pre-commit run djlint-reformat-django
To ease development, we use pre-commit to run all our linters before each commit.
We try to follow the same rules as the angular project towards commits. Each commit is constituted from a summary line, a body and eventually a footer. Each part are separated with a blank line.
The summary line is as follows: <type>(<scope>): <short description>
. It must not end with a dot and must be written in present imperative. Don't capitalize the fist letter. The whole line shouldn't be longer than 80 characters and if possible be between 70 and 75 characters. This is intended to have better logs.
The possible types are:
chore
for changes in the build process or auxiliary tools.doc
for documentationfeat
for new featuresref
: for refactoringstyle
for modifications that not change the meaning of the code.test
: for testsThe body should be written in imperative. It can contain multiple paragraph. Feel free to use bullet points.
Use the footer to reference issue, pull requests or other commits.
This is a full example:
feat(css): use CSS sprites to speed page loading
- Generate sprites with the gulp-sprite-generator plugin.
- Add a build-sprites task in gulpfile
Close #24
Browse the project history to see how contributors last did it in the past!
Apps are useful to structure the project. To create a new one, use the commands below:
APP_NAME=<APP_NAME>
mkdir legadilo/$APP_NAME
django-admin startapp --template .app-template $APP_NAME legadilo/$APP_NAME
Don’t forget to add it to INSTALLED_APPS
!
See this page.