Replaced the Markdown README with its reStructuredText version.

This commit is contained in:
依瑪貓 2021-02-03 10:57:24 +08:00
parent ea8af57fcb
commit 1cc9b1732b
2 changed files with 250 additions and 227 deletions

227
README.md
View File

@ -1,227 +0,0 @@
# mia-accounting
The Django Accounting application.
## Description
`mia-accounting` is a Django accounting application. It was a re-write of my
own private accounting application written in Perl for `mod_perl` in 2007. The
revision aims to be mobile-friendly with Bootstrap, with a modern back-end
framework and front-end technology like jQuery. The first revision was in
Perl / Mojolicious in 2019. This is the second revision in Python / Django
in 2020.
`mia-accounting` comes with two parts:
* The `accounting` application contains the main accounting application.
* The `mia_core` application contains core shared libraries that are used by the
accounting application and my other applications.
You may try it in live demonstration at
https://accounting.imacat.idv.tw/accounting .
* Username: `admin`
* Password: `12345`
## Installation
### Install
`mia-accounting` requires Python 3.6 or above to work.
Install `mia-accounting` with `pip`.
```
pip install mia-accounting
```
### `settings.py`
Add these two applications in the `INSTALL_APPS` section of your `settings.py`.
```
INSTALLED_APPS = [
'mia_core.apps.MiaCoreConfig',
'accounting.apps.AccountingConfig',
...
]
```
Make sure the locale middleware is in the `MIDDLEWARE` section of your
`settings.py`, and add it if it is not added yet.
```
MIDDLEWARE = [
...
'django.middleware.locale.LocaleMiddleware',
...
]
```
### `urls.py`
Add the `accounting` application in the `urlpatterns` of your `urls.py`.
```
urlpatterns = [
...
path('accounting/', decorator_include(login_required, 'accounting.urls')),
...
]
```
Make sure `i18n` and `jsi18n` are also in the `urlpatterns` of your `urls.py`,
and add them if they are not added yet.
```
urlpatterns = [
...
path('i18n/', include("django.conf.urls.i18n")),
path('jsi18n/', JavaScriptCatalog.as_view(), name='javascript-catalog'),
...
]
```
### `base.html`
Add the following to the very beginning of your base template
`base.html`, before your first real HTML tag.
```
{% load mia_core %}
{% init_libs %}
{% block settings %}{% endblock %}
```
Add the CSS and JavaScripts in the `<head>...</head>` section of your
base template `base.html`.
```
{% for css in libs.css %}
<link rel="stylesheet" type="text/css" href="{% if css|is_static_url %}{% static css %}{% else %}{{ css }}{% endif %}" />
{% endfor %}
{% for js in libs.js %}
<script src="{% if js|is_static_url %}{% static js %}{% else %}{{ js }}{% endif %}"></script>
{% endfor %}
```
### Database Initialization
Run the management commands to initialize the database.
```
./manage.py makemigrations
./manage.py migrate accounting
./manage.py accounting_accounts
```
Optionally you can populate the database with some sample data.
```
./manage.py accounting_sample
```
### Restart Your Web Project
## Advanced Settings
The following advanced settings are available in `settings.py`.
```
# Settings for the accounting application
ACCOUNTING = {
# The default cash acount, for ex., "0" (current assets and liabilities),
# "1111" (cash on hand), "1113" (cash in banks) or any
"DEFAULT_CASH_ACCOUNT": "1111",
# The shortcut cash accounts
"CASH_SHORTCUT_ACCOUNTS": ["0", "1111"],
# The default ledger account
"DEFAULT_LEDGER_ACCOUNT": "1111",
# The payable accounts to track
"PAYABLE_ACCOUNTS": ["2141"],
# The asset accounts to track
"EQUIPMENT_ACCOUNTS": ["1441"],
}
# The local static CSS and JavaScript libraries
# The default is to use the libraries from CDN. You may set them to use the
# local static copies of these libraries
STATIC_LIBS = {
"jquery": {"css": [], "js": ["jquery/jquery-3.5.1.min.js"]},
"bootstrap4": {"css": ["bootstrap4/css/bootstrap.min.css"],
"js": ["bootstrap4/js/bootstrap.bundle.min.js"]},
"font-awesome-5": {"css": ["font-awesome-5/css/all.min.css"],
"js": []},
"bootstrap4-datatables": {
"css": ["datatables/css/jquery.dataTables.min.css",
"edatatables/css/dataTables.bootstrap4.min.css"],
"js": ["datatables/js/jquery.dataTables.min.js",
"datatables/js/dataTables.bootstrap4.min.js"]},
"jquery-ui": {"css": ["jquery-ui/jquery-ui.min.css"],
"js": ["jquery-ui/jquery-ui.min.js"]},
"bootstrap4-tempusdominus": {
"css": [("tempusdominus-bootstrap-4/css/"
"tempusdominus-bootstrap-4.min.css")],
"js": ["moment/moment-with-locales.min.js",
("tempusdominus-bootstrap-4/js/"
"tempusdominus-bootstrap-4.min.js")]},
"decimal.js": {"css": [], "js": ["decimal/decimal.min.js"]},
}
# The default static stylesheets to include. Default is none.
DEFAULT_CSS = ["css/app.css"]
# The default static JavaScript to include. Default is none.
DEFAULT_JS = ["js/app.js"]
# The regular accounts in the summary helper. They should be lists of tuples
# of (generic title, title format, account code).
#
# The following variables are available. Variables are surrounded in brackets.
#
# month_no: The numeric month of the current date
# month_name: The month name of the current date
# last_month_no: The numeric previous month of the current date
# last_month_name: The previous month name of the current date
# last_bimonthly_from_no: The first month number of the last bimonthly period
# last_bimonthly_from_name: The first month name of the last bimonthly period
# last_bimonthly_to_no: The second month number of the last bimonthly period
# last_bimonthly_to_name: The second month name of the last bimonthly period
#
REGULAR_ACCOUNTS = {
"debit": [
("Rent", "Rent for (month_name)", "6252"),
("Gas bill",
"Gas bill for (last_bimonthly_from_name)-(last_bimonthly_to_name)",
"6261"),
],
"credit": [
("Payroll", "Payroll for (last_month_name)", "46116"),
],
}
```
## Bugs and Supports
The `mia-accounting` project is hosted on GitHub.
https://github.com/imacat/mia-accounting
Address all bugs and support requests to imacat@mail.imacat.idv.tw.
## Copyright
```
Copyright (c) 2020 imacat.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```

250
README.rst Normal file
View File

@ -0,0 +1,250 @@
######################################
The Mia! Django Accounting Application
######################################
***********
Description
***********
*mia-accounting* is a `Django <https://www.djangoproject.com>`_
accounting application. It was rewritten from my own private
accounting application in Perl/`mod_perl <https://perl.apache.org>`_
in 2007. The revision aims to be mobile-friendly with Bootstrap, with
a modern back-end framework and front-end technology like jQuery. The
first revision was in Perl/`Mojolicious <https://mojolicious.org/>`_
in 2019. This is the second revision in Python/Django in 2020.
The Mia! Django accounting application comes with two parts:
- The ``accounting`` application contains the main accounting
application.
- The ``mia_core`` application contains core shared libraries that are
used by the ``accounting`` application and my other applications.
You may try it in live demonstration at:
- URL: https://accounting.imacat.idv.tw/accounting
- Username: ``admin``
- Password: ``12345``
************
Installation
************
Install
#######
The Mia! Django accounting application requires Python 3.6 or above
to work.
Install ``mia-accounting`` with ``pip``.
.. code::
pip install mia-accounting
``settings.py``
###############
Add these two applications in the ``INSTALL_APPS`` section of your
``settings.py``.
.. code::
INSTALLED_APPS = [
'mia_core.apps.MiaCoreConfig',
'accounting.apps.AccountingConfig',
...
]
Make sure the locale middleware is in the ``MIDDLEWARE`` section of
your ``settings.py``, and add it if it is not added yet.
.. code::
MIDDLEWARE = [
...
'django.middleware.locale.LocaleMiddleware',
...
]
``urls.py``
###########
Add the ``accounting`` application in the ``urlpatterns`` in your
``urls.py``.
.. code::
urlpatterns = [
...
path('accounting/', decorator_include(login_required, 'accounting.urls')),
...
]
Make sure ``i18n`` and ``jsi18n`` are also in the ``urlpatterns`` of
your ``urls.py``, and add them if they are not added yet.
.. code::
urlpatterns = [
...
path('i18n/', include("django.conf.urls.i18n")),
path('jsi18n/', JavaScriptCatalog.as_view(), name='javascript-catalog'),
...
]
``base.html``
#############
Add the following to the very beginning of your base template
``base.html``, before your first real HTML tag.
.. code::
{% load mia_core %}
{% init_libs %}
{% block settings %}{% endblock %}
Add the CSS and JavaScripts in the ``<head>...</head>`` section of your
base template ``base.html``.
.. code::
{% for css in libs.css %}
<link rel="stylesheet" type="text/css" href="{% if css|is_static_url %}{% static css %}{% else %}{{ css }}{% endif %}" />
{% endfor %}
{% for js in libs.js %}
<script src="{% if js|is_static_url %}{% static js %}{% else %}{{ js }}{% endif %}"></script>
{% endfor %}
Database Initialization
#######################
Run the management commands to initialize the database.
.. code::
./manage.py migrate accounting
./manage.py accounting_accounts
Optionally you can populate the database with some sample data.
.. code::
./manage.py accounting_sample
Restart Your Web Server
#######################
And you are done.
*****************
Advanced Settings
*****************
The following advanced settings are available in ``settings.py``.
.. code::
# Settings for the accounting application
ACCOUNTING = {
# The default cash account, for ex., "0" (current assets and liabilities),
# "1111" (cash on hand), "1113" (cash in banks) or any
"DEFAULT_CASH_ACCOUNT": "1111",
# The shortcut cash accounts
"CASH_SHORTCUT_ACCOUNTS": ["0", "1111"],
# The default ledger account
"DEFAULT_LEDGER_ACCOUNT": "1111",
# The payable accounts to track
"PAYABLE_ACCOUNTS": ["2141"],
# The asset accounts to track
"EQUIPMENT_ACCOUNTS": ["1441"],
}
# The local static CSS and JavaScript libraries
# The default is to use the libraries from CDN. You may set them to use the
# local static copies of these libraries
STATIC_LIBS = {
"jquery": {"css": [], "js": ["jquery/jquery-3.5.1.min.js"]},
"bootstrap4": {"css": ["bootstrap4/css/bootstrap.min.css"],
"js": ["bootstrap4/js/bootstrap.bundle.min.js"]},
"font-awesome-5": {"css": ["font-awesome-5/css/all.min.css"],
"js": []},
"bootstrap4-datatables": {
"css": ["datatables/css/jquery.dataTables.min.css",
"datatables/css/dataTables.bootstrap4.min.css"],
"js": ["datatables/js/jquery.dataTables.min.js",
"datatables/js/dataTables.bootstrap4.min.js"]},
"jquery-ui": {"css": ["jquery-ui/jquery-ui.min.css"],
"js": ["jquery-ui/jquery-ui.min.js"]},
"bootstrap4-tempusdominus": {
"css": [("tempusdominus-bootstrap-4/css/"
"tempusdominus-bootstrap-4.min.css")],
"js": ["moment/moment-with-locales.min.js",
("tempusdominus-bootstrap-4/js/"
"tempusdominus-bootstrap-4.min.js")]},
"decimal.js": {"css": [], "js": ["decimal/decimal.min.js"]},
}
# The default static stylesheets to include. Default is none.
DEFAULT_CSS = ["css/app.css"]
# The default static JavaScript to include. Default is none.
DEFAULT_JS = ["js/app.js"]
# The regular accounts in the summary helper. They should be lists of tuples
# of (generic title, summary format, account code).
#
# The following variables are available. Variables are surrounded in brackets.
#
# month_no: The numeric month of the current date
# month_name: The month name of the current date
# last_month_no: The numeric previous month of the current date
# last_month_name: The previous month name of the current date
# last_bimonthly_from_no: The first month number of the last bimonthly period
# last_bimonthly_from_name: The first month name of the last bimonthly period
# last_bimonthly_to_no: The second month number of the last bimonthly period
# last_bimonthly_to_name: The second month name of the last bimonthly period
#
REGULAR_ACCOUNTS = {
"debit": [
("Rent", "Rent for (month_name)", "6252"),
("Gas bill",
"Gas bill for (last_bimonthly_from_name)-(last_bimonthly_to_name)",
"6261"),
],
"credit": [
("Payroll", "Payroll for (last_month_name)", "46116"),
],
}
Bugs and Supports
#################
The Mia! Django accounting application is hosted on GitHub.
https://github.com/imacat/mia-accounting
Address all bugs and support requests to imacat@mail.imacat.idv.tw.
Copyright
#########
Copyright (c) 2020-2021 imacat.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.