Skip to content

Commit

Permalink
Merge pull request #826 from austinmatherne-wk/XT-3111
Browse files Browse the repository at this point in the history 
Add support documentation to RTD project
  • Loading branch information
@derekgengenbacher-wf
derekgengenbacher-wf committed Aug 16, 2023
2 parents 68d99b2 + ea4d8cc commit 9ca01a2
Show file tree
Hide file tree
Showing 20 changed files with 439 additions and 223 deletions.
138 changes: 68 additions & 70 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,80 +1,82 @@
<div align="center">
<img src="http://arelle.org/arelle/wp-content/themes/platform/images/logo-platform.png">
</div>

# Contributing guidelines

## Reporting issues

Please report issues to the [issue tracker](https://github.com/arelle/arelle/issues).

* Check that the issue has not already been reported.
* Check that the issue has not already been fixed in the latest code.
* Be clear and precise (do not prose, but name functions and commands exactly).
* Include the version of Arelle.

# Contributing

## Pull Request Checklist

Before sending your pull requests, make sure you do the following:
We'd love for you to contribute to Arelle, but before you hit that "submit" button,
make sure to:

* Read the [contributing guidelines](CONTRIBUTING.md).
* Ensure you have signed the [Contributor License Agreement (CLA)](#conttributor-license-agreements).
* Check if your changes are consistent with the [guidelines](#general-guidelines-and-philosophy-for-contribution).
* Changes are consistent with the [Coding Style](#python-coding-style).
* Sign and submit a [Contributor License Agreement](#contributor-license-agreements).
It's a legal thing; we'll explain below.
* See if your changes play nice with our [guidelines](#general-guidelines-and-philosophy-for-contributions).
* Make sure your code aligns with our [Coding Style](#python-coding-style).

## How To Become a Code Contributor

## How to become a contributor and submit your own code
### Contributor License Agreements

We'd love to accept your commits! But first, some legal bits:

### Contributor License Agreements
* If you are an individual writing original source code, sign an [individual CLA][cla-individual].
* If you work for a company that wants to allow you to contribute your work, sign
a [corporate CLA][cla-corporate].

Follow the links to get everything sorted. Email the signed form to <Support@arelle.org>,
and we'll be ready to take your pull requests.

We'd love to accept your commits! Before we can take them, we have to jump a couple of legal hurdles.
***NOTE***: Only original source code from people who have signed the CLA can be
accepted into the main repository.

Please fill out either the individual or corporate Contributor License Agreement (CLA).
[cla-corporate]: https://arelle.org/arelle/wp-content/uploads/2010/11/ContributorLicenseForEmployees.txt
[cla-individual]: https://arelle.org/arelle/wp-content/uploads/2010/11/ContributorLicenseForIndividuals.txt

* If you are an individual writing original source code, then you'll need to sign an [individual CLA](https://arelle.org/arelle/wp-content/uploads/2010/11/ContributorLicenseForIndividuals.txt).
* If you work for a company that wants to allow you to contribute your work, then you'll need to sign a [corporate CLA](https://arelle.org/arelle/wp-content/uploads/2010/11/ContributorLicenseForEmployees.txt).
### Setting Up Your Environment

Follow either of the two links above to access the appropriate CLA and instructions for how to sign and
return it. Once we receive it, we'll be able to accept your pull requests.
You'll be working with Python. The Arelle implementation aims to support all stable
versions of Python (not prerelease versions) that are [still receiving security support][python-supported-versions].
Here's how to set up your environment:

***NOTE***: Only original source code from you and other people that have signed the CLA can be accepted into the main repository.
1. [Fork][fork-arelle] the Arelle repo
2. Clone your fork: `git clone git@github.com:<your-github-username>/Arelle.git`
3. Install [pyenv][pyenv-install]
4. Install a supported version of Python.
For example, `pyenv install 3.11.4`
5. Create a virtual env using the Python version you just installed.
For example, `PYENV_VERSION=3.11.4 pyenv exec python -m venv venv`
6. Activate your environment: `source venv/bin/activate`
7. Install dependencies: `pip install -r requirements-dev.txt`
8. Verify you can run the app
1. GUI: `python arelleGUI.pyw`
2. CLI: `python arelleCmdLine.py`

### Setting up an environment
1. Install [pyenv](https://github.com/pyenv/pyenv#installation)
2. Install a [supported version of Python](https://github.com/Arelle/Arelle/blob/master/README.md#installation). For example, `pyenv install 3.11:4`
3. Create a virtual env using the minimum python version. For example, `PYENV_VERSION=3.11.4 pyenv exec python -m venv venv`
4. Activate your environment `source venv/bin/activate`
5. Install dependencies `pip install -r requirements-dev.txt`
6. Verify you can run the app
1. GUI `python arelleGUI.pyw`
2. CLI `python arelleCmdLine.py`
[fork-arelle]: https://github.com/Arelle/Arelle/fork
[pyenv-install]: https://github.com/pyenv/pyenv#installation
[python-supported-versions]: https://devguide.python.org/versions/#supported-versions

### Contributing code
### Contributing Code

If you have improvements or bug fixes for Arelle, send us your pull requests! For those
just getting started, Github has a [how to](https://help.github.com/articles/using-pull-requests/).
If you have improvements or bug fixes for Arelle, send us your pull requests!
For those just getting started, Github has a [how to][using-pull-requests].

Arelle team members will be assigned to review your pull requests. Once the
pull requests are approved and tested an Arelle team member will merge your request.
Arelle team members will be assigned to review your pull requests. Once the pull
requests are approved and tested an Arelle team member will merge your request.

If you want to contribute, start working through the Arelle codebase,
navigate to the
[Github "issues" tab](https://github.com/arelle/arelle/issues) and start
looking through interesting issues. If you decide to start on an issue, leave a
comment so that other people know that you're working on it. If you want to help
out, but not alone, use the issue comment thread to coordinate.
If you want to contribute, start working through the Arelle codebase, navigate to
the [Github "issues" tab][github-issue-tracker] and start looking through interesting
issues. If you decide to start on an issue, leave a comment so that other people
know that you're working on it. If you want to help out, but not alone, use the
issue comment thread to coordinate.

[github-issue-tracker]: https://github.com/Arelle/Arelle/issues
[using-pull-requests]: https://help.github.com/articles/using-pull-requests/

### Contribution guidelines and standards
### Contribution Guidelines and Standards

Before sending your pull request for [review](https://github.com/arelle/arelle/pulls),
make sure your changes are consistent with the guidelines and follow the
Arelle coding style.
Before submitting your pull request for [review][github-pull-requests], make sure
your changes are consistent with the guidelines and follow the Arelle coding style.

[github-pull-requests]: https://github.com/arelle/arelle/pulls

#### General guidelines and philosophy for contribution
#### General Guidelines and Philosophy for Contributions

* When you contribute a bug fix to Arelle, make sure to fully document the bug and
how it was fixed in the PR. Additionally, supply possible ways that the fix could
Expand All @@ -91,26 +93,22 @@ Arelle coding style.
is (by default) transferred to the Arelle team. This means that the benefit
of the contribution must be compared against the cost of maintaining the feature.

#### How To Craft a Good Commit Message

#### Commit messages

Write commit messages according to the following guidance:

* If necessary, add one or more paragraphs with details, wrapped at 72
characters.
* Use present tense and write in the imperative: “Fix bug”, not “fixed bug” or
“fixes bug”.
* Separate paragraphs by blank lines.
* Do *not* use special markup (e.g. Markdown). Commit messages are plain text.

* Write one or more paragraphs with details, wrapped at 72 characters.
* Write in the present tense: "Fix bug" not "Fixed bug".
* Separate paragraphs with a single blank line.
* No markup, please! Commit messages should be plain text.

#### License
#### Include a License

Include a license at the top of new files.
Include a license at the top of new Python files ([example][python-license-example]).

* [Python license example](https://github.com/Arelle/Arelle/blob/a0a6fbc0bc901262dbab0dd6aad3b45313e5ab8e/arelle/plugin/validate/ESEF/__init__.py#L12-L13)
[python-license-example]: https://github.com/Arelle/Arelle/blob/4e88da3b8e8edd368ffb50be01b7daf0324dda4c/arelle/plugin/validate/ESEF/__init__.py#L10

#### Python Coding Style

#### Python coding style
Stick to the [PEP8 guidelines][pep-0008] and use `mixedCase` for variable and function
names.

Changes to Arelle Python code should conform to [PEP8 guidelines](https://www.python.org/dev/peps/pep-0008/)
[pep-0008]: https://www.python.org/dev/peps/pep-0008/
2 changes: 2 additions & 0 deletions COPYRIGHT.md
View file
Original file line number Diff line number Diff line change
@@ -1 +1,3 @@
# Copyright

(c) Copyright 2011-present Workiva, Inc.
111 changes: 66 additions & 45 deletions LICENSE.md
View file
Original file line number Diff line number Diff line change
@@ -1,81 +1,102 @@
# License

## Arelle®

Copyright © 2010-2022 Workiva Inc.

Copyright © 2011-present Workiva, Inc.

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](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.

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.

---
Arelle includes a number of subcomponents with separate copyright notices
and/or license terms. Your use of the source code for these subcomponents
is subject to the terms and conditions of the following licenses:

### Core product not including GUI operation
Arelle includes a number of libraries with separate copyright notices and/or
license terms. Your use of the source code for these libraries is subject to the
terms and conditions of the following licenses:

Python®: Copyright (c) 2001-2022 Python Software Foundation; All Rights Reserved. [License](https://docs.python.org/3/license.html)
## Core product not including GUI operation

aniso8601: Copyright (c) 2021, Brandon Nielsen, All rights reserved. [License](https://github.com/sloanlance/aniso8601/blob/master/LICENSE)
Python®: Copyright (c) 2001-2022 Python Software Foundation; All Rights Reserved.
[License](https://docs.python.org/3/license.html)

cherrypy: cheroot Copyright © 2004-2020, CherryPy Team. All rights reserved. [License](https://github.com/cherrypy/cherrypy/blob/main/LICENSE.md)
aniso8601: Copyright (c) 2021, Brandon Nielsen, All rights reserved.
[License](https://github.com/sloanlance/aniso8601/blob/master/LICENSE)

cx_Freeze: Copyright © 2020-2022, Marcelo Duarte, 2007-2020, Anthony Tuininga, 2001-2006, Computronix (Canada) Ltd., Edmonton, Alberta, Canada. All rights reserved. [License](https://cx-freeze.readthedocs.io/en/latest/license.html)
cherrypy: cheroot Copyright © 2004-2020, CherryPy Team. All rights reserved.
[License](https://github.com/cherrypy/cherrypy/blob/main/LICENSE.md)

graphviz: Copyright (c) 2013-2021 Sebastian Bank [License](https://graphviz.org/license/)
cx_Freeze: Copyright © 2020-2022, Marcelo Duarte, 2007-2020, Anthony Tuininga,
2001-2006, Computronix (Canada) Ltd., Edmonton, Alberta, Canada. All rights reserved.
[License](https://cx-freeze.readthedocs.io/en/latest/license.html)

holidays: Copyright (c) 2014-2017, 2017-2021 [License](https://github.com/dr-prodigy/python-holidays/blob/master/LICENSE)
graphviz: Copyright (c) 2013-2021 Sebastian Bank
[License](https://graphviz.org/license/)

isodate: Copyright 2009, Gerhard Weis. All rights reserved. [License](https://opensource.org/licenses/BSD-3-Clause)
holidays: Copyright (c) 2014-2017, 2017-2021
[License](https://github.com/dr-prodigy/python-holidays/blob/master/LICENSE)

lxml: Copyright 2004-2022 Ifrae. [License](https://github.com/lxml/lxml/blob/master/LICENSES.txt)
isodate: Copyright 2009, Gerhard Weis. All rights reserved.
[License](https://opensource.org/licenses/BSD-3-Clause)

matplotlib: [Copyright](https://matplotlib.org/stable/users/project/license.html) [License](https://github.com/matplotlib/matplotlib/blob/main/LICENSE/LICENSE)
lxml: Copyright 2004-2022 Ifrae.
[License](https://github.com/lxml/lxml/blob/master/LICENSES.txt)

numpy: Copyright (c) 2005-2022, NumPy Developers. All rights reserved. [License](https://numpy.org/doc/stable/license.html)
matplotlib:
[Copyright](https://matplotlib.org/stable/users/project/license.html)
[License](https://github.com/matplotlib/matplotlib/blob/main/LICENSE/LICENSE)

openpyxl Copyright (c) 2010 openpyxl [License](https://github.com/fluidware/openpyxl/blob/master/LICENCE)
numpy: Copyright (c) 2005-2022, NumPy Developers. All rights reserved.
[License](https://numpy.org/doc/stable/license.html)

Pillow: Copyright © 2010-2022 by Alex Clark and contributors [License](https://github.com/python-pillow/Pillow/blob/main/LICENSE)
openpyxl Copyright (c) 2010 openpyxl
[License](https://github.com/fluidware/openpyxl/blob/master/LICENCE)

pycountry: Copyright (c) 2008-2015 gocept gmbh & co. kg [License](https://pypi.org/project/gocept.country/)
Pillow: Copyright © 2010-2022 by Alex Clark and contributors
[License](https://github.com/python-pillow/Pillow/blob/main/LICENSE)

PyParsing: Copyright © 2003-2022 Paul McGuire. [License](https://github.com/pyparsing/pyparsing/blob/master/LICENSE)
pycountry: Copyright (c) 2008-2015 gocept gmbh & co. kg
[License](https://pypi.org/project/gocept.country/)

rdflib: Copyright (c) 2002-2021, RDFLib Team. All rights reserved. [License](https://opensource.org/licenses/BSD-3-Clause)
PyParsing: Copyright © 2003-2022 Paul McGuire.
[License](https://github.com/pyparsing/pyparsing/blob/master/LICENSE)

regex: Copyright (c) 1998-2001 by Secret Labs AB. [License](https://github.com/mrabarnett/mrab-regex/blob/hg/LICENSE.txt)
rdflib: Copyright (c) 2002-2021, RDFLib Team. All rights reserved.
[License](https://opensource.org/licenses/BSD-3-Clause)

tornado: Copyright 2009 Facebook [License](https://github.com/tornadoweb/tornado/blob/master/LICENSE)
regex: Copyright (c) 1998-2001 by Secret Labs AB.
[License](https://github.com/mrabarnett/mrab-regex/blob/hg/LICENSE.txt)

### Operation with GUI
tornado: Copyright 2009 Facebook
[License](https://github.com/tornadoweb/tornado/blob/master/LICENSE)

Bottle: © Copyright 2009-2022, Marcel Hellkamp [License](https://bottlepy.org/docs/dev/)
## Operation with GUI

TkTable: Copyright 1997-2002, Jeffrey Hobbs [License](https://github.com/nbro/tktable/blob/master/LICENSE.md)
Bottle: © Copyright 2009-2022, Marcel Hellkamp
[License](https://bottlepy.org/docs/dev/)

### Operations using Database
TkTable: Copyright 1997-2002, Jeffrey Hobbs
[License](https://github.com/nbro/tktable/blob/master/LICENSE.md)

pg8000: Copyright (c) 2007-2009, Mathieu Fenniak. All rights reserved. [License](https://opensource.org/licenses/BSD-3-Clause)
## Operations using Database

pymysql: Copyright (c) 2010, 2013 PyMySQL contributors [License](https://opensource.org/licenses/MIT)
pg8000: Copyright (c) 2007-2009, Mathieu Fenniak. All rights reserved.
[License](https://opensource.org/licenses/BSD-3-Clause)

pyodbc: No copyright. [License](https://github.com/mkleehammer/pyodbc/blob/master/LICENSE.txt)
pymysql: Copyright (c) 2010, 2013 PyMySQL contributors
[License](https://opensource.org/licenses/MIT)

### Plug-in Modules
pyodbc: No copyright.
[License](https://github.com/mkleehammer/pyodbc/blob/master/LICENSE.txt)

Arelle includes plug-in modules which end-users may activate, some have author-specific licensing terms noted in each _ _init__.py header and _ _pluginInfo__ structure.
## Plug-in Modules

For example, modules contributed by or maintained by U.S. SEC have a copyright notice "{module} was created by staff of the U.S. Securities and Exchange Commission. Data and content created by government employees within the scope of their employment are not subject to domestic copyright protection. 17 U.S.C. 105."
Arelle includes plug-in modules which end-users may activate, some have
author-specific licensing terms noted in each `__init__.py` header and
`__pluginInfo__` structure.

---
For example, modules contributed by or maintained by U.S. SEC have a copyright
notice "{module} was created by staff of the U.S. Securities and Exchange
Commission. Data and content created by government employees within the scope of
their employment are not subject to domestic copyright protection. 17 U.S.C. 105."

0 comments on commit 9ca01a2

Please sign in to comment.