diff --git a/doc-ng/.vitepress/config.mjs b/doc-ng/.vitepress/config.mjs index 94fe5832b..9d1208704 100644 --- a/doc-ng/.vitepress/config.mjs +++ b/doc-ng/.vitepress/config.mjs @@ -5,81 +5,91 @@ export default defineConfig({ // Use Canonical URL, but only the path and with no trailing / // End result is like: `/en/latest` // https://docs.readthedocs.com/platform/stable/intro/vitepress.html#using-the-proper-base-path - base: process.env.READTHEDOCS_CANONICAL_URL ? new URL(process.env.READTHEDOCS_CANONICAL_URL).pathname.replace(/\/$/, "") : "", - title: "Modoboa Documentation ", + base: process.env.READTHEDOCS_CANONICAL_URL + ? new URL(process.env.READTHEDOCS_CANONICAL_URL).pathname.replace(/\/$/, '') + : '', + title: 'Modoboa Documentation ', titleTemplate: ':title', - description: "Modoboa documentation", + description: 'Modoboa documentation', srcExclude: ['public/**/*.md'], - ignoreDeadLinks: [ - /^https?:\/\/localhost:*/, - ], + ignoreDeadLinks: [/^https?:\/\/localhost:*/], metaChunk: true, themeConfig: { // https://vitepress.dev/reference/default-theme-config nav: [ { text: 'Home', link: '/' }, - { text: 'Installation', items: [ - { text: 'Requirements', link: '/installation/requirements'}, - { text: 'Manual Installation', link: '/installation/manual'}, - { text: 'Modoboa Installer', link: '/installation/installer' }, - { text: 'Upgrade Instance', link: '/installation/upgrade' }, - { text: 'Configuration', link: '/configuration' }, - ]}, - { text: 'Contributing', items: [ - { text: 'Getting Start', link: '/contributing/getting_start'}, - { text: 'Write Plugin', link: '/contributing/plugin_api'}, - { text: 'Translate', link: '/contributing/translation'}, - { text: 'Contributor', link: '/contributors'}, - ]} + { + text: 'Installation', + items: [ + { text: 'Requirements', link: '/installation/requirements' }, + { text: 'Manual Installation', link: '/installation/manual' }, + { text: 'Modoboa Installer', link: '/installation/installer' }, + { text: 'Upgrade Instance', link: '/installation/upgrade' }, + { text: 'Configuration', link: '/configuration' }, + ], + }, + { + text: 'Contributing', + items: [ + { text: 'Getting Started', link: '/contributing/getting_start' }, + { text: 'Write a Plugin', link: '/contributing/plugin_api' }, + { text: 'Translate', link: '/contributing/translation' }, + { text: 'Contributors', link: '/contributors' }, + ], + }, ], sidebar: { - "/installation/": [{ - text: 'Manual', - items: [ - { text: 'Modoboa', link: '/installation/modoboa' }, - { text: 'WebServer', link: '/installation/webserver' }, - { text: 'Dovecot', link: '/installation/dovecot' }, - { text: 'Postfix', link: '/installation/postfix' }, - { text: 'OpenDKIM', link: '/installation/opendkim' }, - { text: 'Radicale', link: '/installation/radicale' }, - { text: 'Amavis', link: '/installation/amavis' }, - ] - }, - { - text: 'Automatic', - items: [ - { text: 'Modoboa Installer', link: '/installation/installer' }, - ] - }], - "/contributing/": [ - { text: 'Getting Start', link: '/contributing/getting_start'}, - { text: 'Write Plugin', link: '/contributing/plugin_api'}, - { text: 'Translate', link: '/contributing/translate'}, - ] - } , + '/installation/': [ + { + text: 'Manual', + items: [ + { text: 'Modoboa', link: '/installation/modoboa' }, + { text: 'WebServer', link: '/installation/webserver' }, + { text: 'Dovecot', link: '/installation/dovecot' }, + { text: 'Postfix', link: '/installation/postfix' }, + { text: 'OpenDKIM', link: '/installation/opendkim' }, + { text: 'Radicale', link: '/installation/radicale' }, + { text: 'Amavis', link: '/installation/amavis' }, + ], + }, + { + text: 'Automatic', + items: [ + { text: 'Modoboa Installer', link: '/installation/installer' }, + ], + }, + ], + '/contributing/': [ + { text: 'Getting Started', link: '/contributing/getting_start' }, + { text: 'Write a Plugin', link: '/contributing/plugin_api' }, + { text: 'Translate', link: '/contributing/translate' }, + ], + }, socialLinks: [ { icon: 'github', link: 'https://github.com/modoboa/modoboa' }, - { icon: 'discord', link: 'https://discord.gg/WuQ3v3PXGR'}, - { icon: 'twitter', link: 'https://modoboa.org/'}, - { icon: { - svg: ` + { icon: 'discord', link: 'https://discord.gg/WuQ3v3PXGR' }, + { + icon: { + svg: ` Transifex - ` - }, link: 'https://app.transifex.com/tonio/modoboa/dashboard/' }, - { icon: 'linkedin', link: 'https://www.linkedin.com/company/102575109'}, + `, + }, + link: 'https://app.transifex.com/tonio/modoboa/dashboard/', + }, + { icon: 'linkedin', link: 'https://www.linkedin.com/company/102575109' }, ], footer: { message: 'Build with Vitepress', - copyright: `Copyright © 2010-${new Date().getUTCFullYear()} Antoine Nguyen` + copyright: `Copyright © 2010-${new Date().getUTCFullYear()} Antoine Nguyen`, }, outline: { - label: "Summmary" + label: 'Summmary', }, docFooter: { prev: false, - next: false + next: false, }, search: { provider: 'local', @@ -88,18 +98,18 @@ export default defineConfig({ text: 'Update at', formatOptions: { dateStyle: 'full', - timeStyle: 'short' - } - } + timeStyle: 'short', + }, + }, }, sitemap: { - hostname: 'https://modoboa.readthedocs.io/en/latest' + hostname: 'https://modoboa.readthedocs.io/en/latest', }, markdown: { lineNumbers: true, image: { - lazyLoading: true - } + lazyLoading: true, + }, }, cleanUrls: true, outDir: './dist', diff --git a/doc-ng/contributing/plugin_api.md b/doc-ng/contributing/plugin_api.md index 5114ac3c9..791dbaa8e 100644 --- a/doc-ng/contributing/plugin_api.md +++ b/doc-ng/contributing/plugin_api.md @@ -2,7 +2,7 @@ ## Introduction -Modoboa offers a plugin API to expand its capabilities. +Modoboa offers a plugin API to expand its capabilities. The current implementation provides the following possibilities: @@ -12,7 +12,7 @@ The current implementation provides the following possibilities: ::: tip Plugins are nothing more than Django applications with an extra piece of -code that integrates them into Modoboa. +code that integrates them into Modoboa. ::: The `modo_extension.py` file will contain a complete description of the plugin: @@ -20,7 +20,7 @@ The `modo_extension.py` file will contain a complete description of the plugin: - Admin and user parameters - Custom menu entries -The communication between both applications is provided by +The communication between both applications is provided by [Django signals](https://docs.djangoproject.com/en/5.2/topics/signals/). The following subsections describe the plugin architecture and explain @@ -56,7 +56,7 @@ class MyExtension(ModoExtension): """This method is called when Modoboa loads available and activated plugins. Declare parameters and register events here. - """ + """ pass def load_initial_data(self): @@ -66,8 +66,8 @@ class MyExtension(ModoExtension): exts_pool.register_extension(MyExtension) ``` -Once done, simply add your extension's module name to the `MODOBOA_APPS` -variable located inside `settings.py`. +Once done, simply add your extension's module name to the `MODOBOA_APPS` +variable located inside `settings.py`. Finally, run the following commands: @@ -88,7 +88,7 @@ A plugin can declare its own parameters. There are two levels available: #### Playing with parameters -Parameters are defined using [Django forms](https://docs.djangoproject.com/en/1.9/topics/forms/) +Parameters are defined using [Django forms](https://docs.djangoproject.com/en/1.9/topics/forms/) and Modoboa adds two special forms you can inherit depending on the level of parameter(s) you want to add: * `modoboa.parameters.forms.AdminParametersForm`: for general parameters @@ -106,7 +106,7 @@ Replace: ### Custom role permissions -Modoboa uses Django's internal permission system. +Modoboa uses Django's internal permission system. Administrative roles are nothing more than groups (`Group` instances). @@ -132,62 +132,3 @@ def extra_role_permissions(sender, role, **kwargs): """Add permissions to the Resellers group.""" return constants.PERMISSIONS.get(role, []) ``` - -### Extending admin forms - -The forms used to edit objects (account, domain, etc.) through the admin panel are composed of tabs. - -You can extend them (ie. add new tabs) in a pretty easy way thanks to custom signals. - -#### Account - -To add a new tab to the account edition form, define new listeners -(handlers) for the following signals: - -* `modoboa.admin.signals.extra_account_forms` -* `modoboa.admin.signals.get_account_form_instances` -* `modoboa.admin.signals.check_extra_account_form` (optional) - -Example: - -``` python -from django.dispatch import receiver -from modoboa.admin import signals as admin_signals - - -@receiver(admin_signals.extra_account_forms) -def extra_account_form(sender, user, account, **kwargs): - return [ - {"id": "tabid", "title": "Title", "cls": MyFormClass} - ] - -@receiver(admin_signals.get_account_form_instances) -def fill_my_tab(sender, user, account, **kwargs): - return {"id": my_instance} -``` - -#### Domain - -To add a new tab to the domain edition form, define new listeners -(handlers) for the following signals: - -* `modoboa.admin.signals.extra_domain_forms` -* `modoboa.admin.signals.get_domain_form_instances` - -Example: - -``` python -from django.dispatch import receiver -from modoboa.admin import signals as admin_signals - - -@receiver(admin_signals.extra_domain_forms) -def extra_account_form(sender, user, domain, **kwargs): - return [ - {"id": "tabid", "title": "Title", "cls": MyFormClass} - ] - -@receiver(admin_signals.get_domain_form_instances) -def fill_my_tab(sender, user, domain, **kwargs): - return {"id": my_instance} -``` diff --git a/doc-ng/contributing/translation.md b/doc-ng/contributing/translation.md index 8bf6ce1f3..000f24f77 100644 --- a/doc-ng/contributing/translation.md +++ b/doc-ng/contributing/translation.md @@ -7,6 +7,17 @@ The project is using Transifex. To start with translation, you will need to create an account and join [modoboa\'s team](https://app.transifex.com/tonio/modoboa/dashboard/) +## API + +Modoboa API code relies on Django's translation system. + +To update translation files after a change to the code, execute the following commands: + +```shell +$ cd modoboa +$ django-admin makemessages -a +``` + ## Frontend When editing the frontend, you may need to update localization files for @@ -16,5 +27,5 @@ To do so, after finishing editing, go to the frontend directory and run the following command: ```shell -$ make makemessages -``` \ No newline at end of file +$ yarn gettext:extract +``` diff --git a/doc-ng/contributors.md b/doc-ng/contributors.md index 3f87980b4..4ae6e3f9c 100644 --- a/doc-ng/contributors.md +++ b/doc-ng/contributors.md @@ -1,5 +1,6 @@ # Contributors +- [6clones](https://www.6clones.fr/) - [Antidot](http://antidot.com) - [Bearstech](http://bearstech.com) - [CAP-REL](https://cap-rel.fr/) diff --git a/doc-ng/installation/requirements.md b/doc-ng/installation/requirements.md index b8a26c5da..8e127fa81 100644 --- a/doc-ng/installation/requirements.md +++ b/doc-ng/installation/requirements.md @@ -2,11 +2,11 @@ You will need a Server to perform well with at least: -- CPU: 2 -- RAM: 2GB +- CPU: 4 +- RAM: 4GB - Disk: 10GB -- Python 3.8+ -- Postgres 12+ or MariaDB 10.4+ or MySQL 8+ or sqlite3 or LDAP +- Python 3.10+ +- Postgres 14+ or MariaDB 10.5+ or MySQL 8.0.11+ or sqlite3 ::: warning @@ -23,4 +23,4 @@ RAM. You have 2 possibilities to install Modoboa * [Manual Installation](manual) -* [Automatic Install](installer) \ No newline at end of file +* [Automatic Install](installer)