Remove and integrate content from contributing.rst

This commit is contained in:
Michael Shamoon 2022-03-20 20:58:57 -07:00
parent 0979f3c5c3
commit 8059039ef4
4 changed files with 47 additions and 160 deletions

View File

@ -1,145 +0,0 @@
.. _contributing:
Contributing to Paperless
#########################
.. warning::
This section is not updated to paperless-ngx yet.
Maybe you've been using Paperless for a while and want to add a feature or two,
or maybe you've come across a bug that you have some ideas how to solve. The
beauty of Free software is that you can see what's wrong and help to get it
fixed for everyone!
How to Get Your Changes Rolled Into Paperless
=============================================
If you've found a bug, but don't know how to fix it, you can always post an
issue on `GitHub`_ in the hopes that someone will have the time to fix it for
you. If however you're the one with the time, pull requests are always
welcome, you just have to make sure that your code conforms to a few standards:
Pep8
----
It's the standard for all Python development, so it's `very well documented`_.
The short version is:
* Lines should wrap at 79 characters
* Use ``snake_case`` for variables, ``CamelCase`` for classes, and ``ALL_CAPS``
for constants.
* Space out your operators: ``stuff + 7`` instead of ``stuff+7``
* Two empty lines between classes, and functions, but 1 empty line between
class methods.
There's more to it than that, but if you follow those, you'll probably be
alright. When you submit your pull request, there's a pep8 checker that'll
look at your code to see if anything is off. If it finds anything, it'll
complain at you until you fix it.
Additional Style Guides
-----------------------
Where pep8 is ambiguous, I've tried to be a little more specific. These rules
aren't hard-and-fast, but if you can conform to them, I'll appreciate it and
spend less time trying to conform your PR before merging:
Function calls
..............
If you're calling a function and that necessitates more than one line of code,
please format it like this:
.. code:: python
my_function(
argument1,
kwarg1="x",
kwarg2="y"
another_really_long_kwarg="some big value"
a_kwarg_calling_another_long_function=another_function(
another_arg,
another_kwarg="kwarg!"
)
)
This is all in the interest of code uniformity rather than anything else. If
we stick to a style, everything is understandable in the same way.
Quoting Strings
...............
pep8 is a little too open-minded on this for my liking. Python strings should
be quoted with double quotes (``"``) except in cases where the resulting string
would require too much escaping of a double quote, in which case, a single
quoted, or triple-quoted string will do:
.. code:: python
my_string = "This is my string"
problematic_string = 'This is a "string" with "quotes" in it'
In HTML templates, please use double-quotes for tag attributes, and single
quotes for arguments passed to Django template tags:
.. code:: html
<div class="stuff">
<a href="{% url 'some-url-name' pk='w00t' %}">link this</a>
</div>
This is to keep linters happy they look at an HTML file and see an attribute
closing the ``"`` before it should have been.
--
That's all there is in terms of guidelines, so I hope it's not too daunting.
Indentation & Spacing
.....................
When it comes to indentation:
* For Python, the rule is: follow pep8 and use 4 spaces.
* For Javascript, CSS, and HTML, please use 1 tab.
Additionally, Django templates making use of block elements like ``{% if %}``,
``{% for %}``, and ``{% block %}`` etc. should be indented:
Good:
.. code:: html
{% block stuff %}
<h1>This is the stuff</h1>
{% endblock %}
Bad:
.. code:: html
{% block stuff %}
<h1>This is the stuff</h1>
{% endblock %}
The Code of Conduct
===================
Paperless has a `code of conduct`_. It's a lot like the other ones you see out
there, with a few small changes, but basically it boils down to:
> Don't be an ass, or you might get banned.
I'm proud to say that the CoC has never had to be enforced because everyone has
been awesome, friendly, and professional.
.. _GitHub: https://github.com/the-paperless-project/paperless/issues
.. _very well documented: https://www.python.org/dev/peps/pep-0008/
.. _code of conduct: https://github.com/the-paperless-project/paperless/blob/master/CODE_OF_CONDUCT.md

View File

@ -1,7 +1,7 @@
.. _extending:
Paperless development
#####################
Paperless-ngx Development
#########################
This section describes the steps you need to take to start development on paperless-ngx.
@ -23,6 +23,31 @@ Apart from that, the folder structure is as follows:
* ``scripts/`` - Various scripts that help with different parts of development.
* ``docker/`` - Files required to build the docker image.
Contributing to Paperless
=========================
Maybe you've been using Paperless for a while and want to add a feature or two,
or maybe you've come across a bug that you have some ideas how to solve. The
beauty of open source software is that you can see what's wrong and help to get
it fixed for everyone!
Before contributing please review our `code of conduct`_ and other important
information in the `contributing guidelines`_.
Code formatting with pre-commit Hooks
=====================================
To ensure a consistent style and formatting across the project source, the project
utilizes a Git `pre-commit` hook to perform some formatting and linting before a
commit is allowed. That way, everyone uses the same style and some common issues
can be caught early on. See below for installation instructions.
Once installed, hooks will run when you commit. If the formatting isn't quite right
or a linter catches something, the commit will be rejected. You'll need to look at the
output and fix the issue. Some hooks, such as the Python formatting tool `black`,
will format failing files, so all you need to do is `git add` those files again and
retry your commit.
Initial setup and first start
=============================
@ -37,13 +62,19 @@ To do the setup you need to perform the steps from the following chapters in a c
$ npm install -g @angular/cli
4. Create ``consume`` and ``media`` folders in the cloned root folder.
4. Install pre-commit
.. code:: shell-session
pre-commit install
5. Create ``consume`` and ``media`` folders in the cloned root folder.
.. code:: shell-session
mkdir -p consume media
5. You can now either ...
6. You can now either ...
* install redis or
* use the included scripts/start-services.sh to use docker to fire up a redis instance (and some other services such as tika, gotenberg and a postgresql server) or
@ -53,41 +84,41 @@ To do the setup you need to perform the steps from the following chapters in a c
docker run -d -p 6379:6379 --restart unless-stopped redis:latest
6. Install the python dependencies by performing in the src/ directory.
7. Install the python dependencies by performing in the src/ directory.
.. code:: shell-session
pipenv install --dev
* Make sure you're using python 3.9.x or lower. Otherwise you might get issues with building dependencies. You can use `pyenv <https://github.com/pyenv/pyenv>`_ to install a specific python version.
7. Generate the static UI so you can perform a login to get session that is required for frontend development (this needs to be done one time only). From src-ui directory:
8. Generate the static UI so you can perform a login to get session that is required for frontend development (this needs to be done one time only). From src-ui directory:
.. code:: shell-session
npm install .
./node_modules/.bin/ng build --configuration production
8. Apply migrations and create a superuser for your dev instance:
9. Apply migrations and create a superuser for your dev instance:
.. code:: shell-session
python3 manage.py migrate
python3 manage.py createsuperuser
9. Now spin up the dev backend. Depending on which part of paperless you're developing for, you need to have some or all of them running.
10. Now spin up the dev backend. Depending on which part of paperless you're developing for, you need to have some or all of them running.
.. code:: shell-session
python3 manage.py runserver & python3 manage.py document_consumer & python3 manage.py qcluster
10. Login with the superuser credentials provided in step 8 at ``http://localhost:8000`` to create a session that enables you to use the backend.
11. Login with the superuser credentials provided in step 8 at ``http://localhost:8000`` to create a session that enables you to use the backend.
Backend development environment is now ready, to start Frontend development go to ``/src-ui`` and run ``ng serve``. From there you can use ``http://localhost:4200`` for a preview.
Back end development
====================
The backend is a django application. I use PyCharm for development, but you can use whatever
The backend is a django application. PyCharm works well for development, but you can use whatever
you want.
Configure the IDE to use the src/ folder as the base source folder. Configure the following
@ -121,9 +152,8 @@ Testing and code style:
Front end development
=====================
The front end is build using angular. I use the ``Code - OSS`` IDE for development.
In order to get started, you need ``npm``. Install the Angular CLI interface with
The front end is built using Angular. In order to get started, you need ``npm``.
Install the Angular CLI interface with
.. code:: shell-session
@ -361,3 +391,6 @@ that returns information about your parser:
download. We could guess that from the file extensions, but some mime types have many extensions
associated with them and the python methods responsible for guessing the extension do not always
return the same value.
.. _code of conduct: https://github.com/paperless-ngx/paperless-ngx/blob/main/CODE_OF_CONDUCT.md
.. _contributing guidelines: https://github.com/paperless-ngx/paperless-ngx/blob/main/CONTRIBUTING.md

View File

@ -70,7 +70,6 @@ Contents
faq
troubleshooting
extending
contributing
scanners
screenshots
changelog

View File

@ -1 +1 @@
__version__ = (1, 5, 0)
__version__ = (1, 6, 0)