# `ixbrl-reporter`
## Summary
This is a command-line utility which creates iXBRL-tagged financial reports
from configuration templates and account data. It currently supports account
information from GnuCash files, and also a CSV file of transactions.
## Discuss
There's a #ixbrl-reporter channel on our Discord server if you want
to discuss... https://discord.gg/3cAvPASS6p
## Note
The configuration files used by ixbrl-reporter are complex. See
[`ixbrl-reporter-jsonnet`](https://github.com/cybermaggedon/ixbrl-reporter-jsonnet) for an easier way to manage the configuration files.
## Summary
This code is intended for use with `ixbrl-reporter`.
Using `ixbrl-reporter` requires a complex configuration file, or set of
configuration files. An internal import/reference mechanism was introduced
to allow the configuration files to be modulariesd, but the mechanism is
still not ideal.
This repo implements JSONNET templates for construction of configuration
files for `ixbrl-reporter` which makes the matter more manageable.
Jsonnet (see jsonnet.org) is a programming language (invented by Google)
which extends JSON with programming constructs. Jsonnet is specifically
designed to make it easy to build configuration files; it supports object
templating and extension.
## iXBRL
The iXBRL format is commonly used to describe regulatory account information
which companies must publish. Different schemas are in use in different
places in the world. The example account and report data included in this
project uses schemas which are used in the UK reporting regime, and there
is also a minimalistic ESEF example, but it is possible to define other
taxonomies.
iXBRL stands for "Inline XBRL". It was built on the XBRL standard
(eXtensible Business Reporting Language). iXBRL is HTML with embedded XBRL
tags so that the document can be viewed in an HTML browser and read by
a human, but the tags are also machine-readable. This allows the same
accounts to be usable by a human, and also by automated data extraction tools.
## Examples
Included in this repo are example accounts and configuration files exist
which output:
- Company accounts for UK Companies House filing using the FRS-102 taxonomy.
- UK HMRC corporation tax filing using the CT600 schema and Detailed Profit
and Loss schema in a single document.
- ESEF filing configuration for an English-language filing as well as
French.
Configuration files can be written for other taxonomies.
## Other outputs
Plain-text report output is supported (semi-useful), as is plain-text
HTML output created by stripping the iXBRL tags.
## Motivation
iXBRL report generation is presently convoluted. Generally people generate
financial reports, or use an accountant to create the reports, and then
send the report files away for a human to semi-automatically tag using an
iXBRL tagging tool, which takes some number of days and costs at least €150.
This tool demonstrates auto-generating reports with the right tags in the
first place.
The overheads in configuring reports and iXBRL output with `ixbrl-reporter`
is not small, but that's an up-front cost, once set-up, up-to-date reports
can be generated.
## Warranty
This code comes with no warranty whatsoever. See the [LICENSE](LICENCE) file
for details. Further, I am not an accountant. Even if I were, I would not be
YOUR accountant. It is possible that this code could be useful to you in
meeting regulatory reporting requirements for your business. It is also
possible that the software could report misleading information which could
land you in a lot of trouble if used for regulatory purposes. Really, you
should check with a qualified accountant.
## Configuration overview
`ixbrl-reporter` configuration is complex: If the configuration files
supplied work for your business you could get accounts with little work.
However, it is very likely that you'll need to tailor the reports to work
with your business. The information flows are described
in [Information flows](docs/information-flows.md).
## Installing
There is a dependency on one of the `gnucash`, `piecash` or `csv` Python
modules:
- The `gnucash` Python support is built from the GnuCash source code tree
itself. It is currently only distributed with Linux packages. You cannot
use this on Windows or MacOS. See
<https://wiki.gnucash.org/wiki/Python_Bindings> for installation, but on
Linux it is generally installed when you install the gnucash package.
It is not possible to install the `gnucash` module using PyPI.
- The `piecash` Python support can be download using `pip` or your favourite
Python package manager. It works on Linux, MacOS and Windows. However,
it only supports the Sqlite or Postgres GnuCash formats, and not the
XML format which is the default.
- The `csv` Python module is bundled with Python.
It is possible to convert a GnuCash file to Sqlite format by using
GnuCash, select Save As... and selecting Sqlite.
```
pip3 install git+https://github.com/cybermaggedon/ixbrl-reporter
```
## Usage
```
ixbrl-reporter <config> <report> <format>
```
Where:
- `config` specifies a configuration file. See
[Configuration File](docs/config.md).
- `report` specifies a report tag.
- `format` specifies output format. `text` outputs plain text, `ixbrl`
outputs iXBRL (XHTML tagged with XBRL tags) and `html` outputs HTML, which
is iXBRL with the XBRL tags removed.
The examples use files in the git repo. Clone the git repo to run this
stuff:
```
git clone https://github.com/cybermaggedon/ixbrl-reporter
```
Example, Companies House accounts. You should be able to view the resultant
HTML in a browser:
```
ixbrl-reporter config.yaml report ixbrl > accts.html
```
Corporation tax filing:
```
ixbrl-reporter config-corptax.yaml report ixbrl > ct.html
```
ESMA ESEF filing:
```
ixbrl-reporter config-esef.yaml report ixbrl > esef.html
```
Check out the awesome Graffiti tool for viewing iXBRL tags in a document.
The basic version is free. It's just a bookmark in your browser! Once
your iXBRL document is loaded in the browser, invoke the bookmark and
iXBRL tag navigation is seamlessly added to the document you are looking at.
https://stechanalytics.com/#Graffiti
## Configuration
All the configuration is in YAML, and there are various configuration
files which are linked together. If the templates work for you, you should
only have to change `config.yaml` and `metadata.yaml`.
- `config.yaml` is the top-level configuration file which imports the
other configuration files. Of interest, is the `accounts` section which
specifies which GnuCash file to use. There is also a `report` setting
which describes which report definition to import. Also a `pretty-print`
setting which causes HTML to be output with indented spacing to make it
easier to read if you have to debug something.
- `metadata.yaml` contains information specific to the business the report
is about, such as name of business, address, company identifiers and so
on. You would edit this to describe your business.
- Taxonomy definitions under the `taxonomy` directory specify the mapping
between identifiers and the iXBRL tagging. If the report templates do
what you need, you won't need to change this.
- Report configuration files under the `report` directory. Think of these
as report templates. They define the structure of information going into
the report. There is a `ch` sub-directory containing various kinds of
Companies House filing templates. Also an `hmrc` sub-directory containing
the HMRC corporation tax filing template. If these report configurations do
what you want, you don't need to change them.
- `directors-report.yaml`, `accountants-report.yaml`, `auditors-report.yaml`,
`notes.yaml` are used to provide specific sections of the company accounts.
These are only needed for more complex reports, for a micro-entity account
filing, these are not used.
All configuration files are YAML.
See [Configuration File](docs/config.md).
## Screenshots of output
[Screenshots](docs/screenshots.md)
## Other things to try
Having created iXBRL, you can try loading into
[Arelle](https://arelle.org/arelle/) which is an iXBRL development tool.
In Arelle, you can invoke a validation and check the output matches the
schema.
Once Arelle is installed, you can install the Workiva
[ixbrl-viewer](https://github.com/Workiva/ixbrl-viewer). When an iXBRL
document is loaded into Arelle, the document is automatically loaded into
a browser with markup so that you can navigate the tags and discover tagged
information. With the iXBRL viewer when you hover over tagged information,
it is highlighted, clicking opens up the metadata viewer.
### Test suite / examples
See the `test` directory.
```
sh test/run_all
```
Output in `output`.
## License
Copyright (c) Accounts Machine Limited, 2020-2022
Licenced under the GPL version 3 licence, see the [LICENSE](LICENCE) file
Raw data
{
"_id": null,
"home_page": "https://github.com/cybermaggedon/ixbrl-reporter",
"name": "ixbrl-reporter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Cybermaggedon",
"author_email": "mark@cyberapocalypse.co.uk",
"download_url": "https://files.pythonhosted.org/packages/07/76/2e0d02492bde53a2febcfaa6063639e25218dd31caed95104efd23885bf2/ixbrl-reporter-1.1.1.tar.gz",
"platform": null,
"description": "\n# `ixbrl-reporter`\n\n## Summary\n\nThis is a command-line utility which creates iXBRL-tagged financial reports\nfrom configuration templates and account data. It currently supports account\ninformation from GnuCash files, and also a CSV file of transactions.\n\n## Discuss\n\nThere's a #ixbrl-reporter channel on our Discord server if you want\nto discuss... https://discord.gg/3cAvPASS6p\n\n## Note\n\nThe configuration files used by ixbrl-reporter are complex. See\n[`ixbrl-reporter-jsonnet`](https://github.com/cybermaggedon/ixbrl-reporter-jsonnet) for an easier way to manage the configuration files.\n\n## Summary\n\nThis code is intended for use with `ixbrl-reporter`.\n\nUsing `ixbrl-reporter` requires a complex configuration file, or set of\nconfiguration files. An internal import/reference mechanism was introduced\nto allow the configuration files to be modulariesd, but the mechanism is\nstill not ideal.\n\nThis repo implements JSONNET templates for construction of configuration\nfiles for `ixbrl-reporter` which makes the matter more manageable.\n\nJsonnet (see jsonnet.org) is a programming language (invented by Google)\nwhich extends JSON with programming constructs. Jsonnet is specifically\ndesigned to make it easy to build configuration files; it supports object\ntemplating and extension.\n\n## iXBRL\n\nThe iXBRL format is commonly used to describe regulatory account information\nwhich companies must publish. Different schemas are in use in different\nplaces in the world. The example account and report data included in this\nproject uses schemas which are used in the UK reporting regime, and there\nis also a minimalistic ESEF example, but it is possible to define other\ntaxonomies.\n\niXBRL stands for \"Inline XBRL\". It was built on the XBRL standard\n(eXtensible Business Reporting Language). iXBRL is HTML with embedded XBRL\ntags so that the document can be viewed in an HTML browser and read by\na human, but the tags are also machine-readable. This allows the same\naccounts to be usable by a human, and also by automated data extraction tools.\n\n## Examples\n\nIncluded in this repo are example accounts and configuration files exist\nwhich output:\n- Company accounts for UK Companies House filing using the FRS-102 taxonomy.\n- UK HMRC corporation tax filing using the CT600 schema and Detailed Profit\n and Loss schema in a single document.\n- ESEF filing configuration for an English-language filing as well as\n French.\n\nConfiguration files can be written for other taxonomies.\n\n## Other outputs\n\nPlain-text report output is supported (semi-useful), as is plain-text\nHTML output created by stripping the iXBRL tags.\n\n## Motivation\n\niXBRL report generation is presently convoluted. Generally people generate\nfinancial reports, or use an accountant to create the reports, and then\nsend the report files away for a human to semi-automatically tag using an\niXBRL tagging tool, which takes some number of days and costs at least \u20ac150.\n\nThis tool demonstrates auto-generating reports with the right tags in the\nfirst place.\n\nThe overheads in configuring reports and iXBRL output with `ixbrl-reporter`\nis not small, but that's an up-front cost, once set-up, up-to-date reports\ncan be generated.\n\n## Warranty\n\nThis code comes with no warranty whatsoever. See the [LICENSE](LICENCE) file\nfor details. Further, I am not an accountant. Even if I were, I would not be\nYOUR accountant. It is possible that this code could be useful to you in\nmeeting regulatory reporting requirements for your business. It is also\npossible that the software could report misleading information which could\nland you in a lot of trouble if used for regulatory purposes. Really, you\nshould check with a qualified accountant.\n\n## Configuration overview\n\n`ixbrl-reporter` configuration is complex: If the configuration files\nsupplied work for your business you could get accounts with little work.\n\nHowever, it is very likely that you'll need to tailor the reports to work\nwith your business. The information flows are described\nin [Information flows](docs/information-flows.md).\n\n## Installing\n\nThere is a dependency on one of the `gnucash`, `piecash` or `csv` Python\nmodules:\n\n- The `gnucash` Python support is built from the GnuCash source code tree\n itself. It is currently only distributed with Linux packages. You cannot\n use this on Windows or MacOS. See\n <https://wiki.gnucash.org/wiki/Python_Bindings> for installation, but on\n Linux it is generally installed when you install the gnucash package.\n It is not possible to install the `gnucash` module using PyPI.\n- The `piecash` Python support can be download using `pip` or your favourite\n Python package manager. It works on Linux, MacOS and Windows. However,\n it only supports the Sqlite or Postgres GnuCash formats, and not the\n XML format which is the default.\n- The `csv` Python module is bundled with Python.\n\nIt is possible to convert a GnuCash file to Sqlite format by using\nGnuCash, select Save As... and selecting Sqlite.\n\n```\npip3 install git+https://github.com/cybermaggedon/ixbrl-reporter\n```\n\n## Usage\n\n```\nixbrl-reporter <config> <report> <format>\n```\n\nWhere:\n- `config` specifies a configuration file. See\n [Configuration File](docs/config.md).\n- `report` specifies a report tag.\n- `format` specifies output format. `text` outputs plain text, `ixbrl`\n outputs iXBRL (XHTML tagged with XBRL tags) and `html` outputs HTML, which\n is iXBRL with the XBRL tags removed.\n\nThe examples use files in the git repo. Clone the git repo to run this\nstuff:\n\n```\ngit clone https://github.com/cybermaggedon/ixbrl-reporter\n```\n\nExample, Companies House accounts. You should be able to view the resultant\nHTML in a browser:\n\n```\nixbrl-reporter config.yaml report ixbrl > accts.html\n```\n\nCorporation tax filing:\n\n```\nixbrl-reporter config-corptax.yaml report ixbrl > ct.html\n```\n\nESMA ESEF filing:\n\n```\nixbrl-reporter config-esef.yaml report ixbrl > esef.html\n```\n\nCheck out the awesome Graffiti tool for viewing iXBRL tags in a document.\nThe basic version is free. It's just a bookmark in your browser! Once\nyour iXBRL document is loaded in the browser, invoke the bookmark and\niXBRL tag navigation is seamlessly added to the document you are looking at.\nhttps://stechanalytics.com/#Graffiti\n\n## Configuration\n\nAll the configuration is in YAML, and there are various configuration\nfiles which are linked together. If the templates work for you, you should\nonly have to change `config.yaml` and `metadata.yaml`.\n\n- `config.yaml` is the top-level configuration file which imports the\n other configuration files. Of interest, is the `accounts` section which\n specifies which GnuCash file to use. There is also a `report` setting\n which describes which report definition to import. Also a `pretty-print`\n setting which causes HTML to be output with indented spacing to make it\n easier to read if you have to debug something.\n- `metadata.yaml` contains information specific to the business the report\n is about, such as name of business, address, company identifiers and so\n on. You would edit this to describe your business.\n- Taxonomy definitions under the `taxonomy` directory specify the mapping\n between identifiers and the iXBRL tagging. If the report templates do\n what you need, you won't need to change this.\n- Report configuration files under the `report` directory. Think of these\n as report templates. They define the structure of information going into\n the report. There is a `ch` sub-directory containing various kinds of\n Companies House filing templates. Also an `hmrc` sub-directory containing\n the HMRC corporation tax filing template. If these report configurations do\n what you want, you don't need to change them.\n- `directors-report.yaml`, `accountants-report.yaml`, `auditors-report.yaml`,\n `notes.yaml` are used to provide specific sections of the company accounts.\n These are only needed for more complex reports, for a micro-entity account\n filing, these are not used.\n\nAll configuration files are YAML.\n\nSee [Configuration File](docs/config.md).\n\n## Screenshots of output\n\n[Screenshots](docs/screenshots.md)\n\n## Other things to try\n\nHaving created iXBRL, you can try loading into\n[Arelle](https://arelle.org/arelle/) which is an iXBRL development tool.\nIn Arelle, you can invoke a validation and check the output matches the\nschema.\n\nOnce Arelle is installed, you can install the Workiva\n[ixbrl-viewer](https://github.com/Workiva/ixbrl-viewer). When an iXBRL\ndocument is loaded into Arelle, the document is automatically loaded into\na browser with markup so that you can navigate the tags and discover tagged\ninformation. With the iXBRL viewer when you hover over tagged information,\nit is highlighted, clicking opens up the metadata viewer.\n\n### Test suite / examples\n\nSee the `test` directory.\n\n```\nsh test/run_all\n```\n\nOutput in `output`.\n\n## License\n\nCopyright (c) Accounts Machine Limited, 2020-2022\nLicenced under the GPL version 3 licence, see the [LICENSE](LICENCE) file\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Production of iXBRL reports from templates and accounts files",
"version": "1.1.1",
"project_urls": {
"Download": "https://github.com/cybermaggedon/ixbrl-reporter/archive/refs/tags/v1.1.0.tar.gz",
"Homepage": "https://github.com/cybermaggedon/ixbrl-reporter"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "07762e0d02492bde53a2febcfaa6063639e25218dd31caed95104efd23885bf2",
"md5": "d09e5b51f7cccc73d027cd5dc014bd7a",
"sha256": "93088bbcf3ac2a37afc03a63ae3552cbb59aafdbc7d6f019e3183037eb5f9458"
},
"downloads": -1,
"filename": "ixbrl-reporter-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "d09e5b51f7cccc73d027cd5dc014bd7a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 48799,
"upload_time": "2024-09-09T23:04:34",
"upload_time_iso_8601": "2024-09-09T23:04:34.496666Z",
"url": "https://files.pythonhosted.org/packages/07/76/2e0d02492bde53a2febcfaa6063639e25218dd31caed95104efd23885bf2/ixbrl-reporter-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-09 23:04:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cybermaggedon",
"github_project": "ixbrl-reporter",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ixbrl-reporter"
}
JSON
