Darren/dpaste
1
0
Fork 0
mirror of https://github.com/DarrenOfficial/dpaste.git synced 2024-12-23 23:23:06 +11:00
Code Issues Projects Releases Packages Wiki Activity

Docs Update

Browse source
This commit is contained in:
Martin Mahner 2019-12-08 19:39:43 +01:00
parent 2fdb6f44f8
commit 5d1b59ca6e
8 changed files with 203 additions and 184 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

17
docs/api.rst
View file

@ -1,5 +1,8 @@
============
API Endpoint
===
API
===
API endpoint
============
dpaste provides a simple API endpoint to create new snippets. All you need to
@ -99,13 +102,13 @@ do is a simple ``POST`` request to the API endpoint, usually ``/api/``:
:statuscode 400: One of the above form options was invalid,
the response will contain a meaningful error message.
.. hint:: If yuo have a standalone installation and your API returns
``https://dpaste.de/`` as the domain, you need to adjust the setting
``BASE_URL`` property. See :ref:`settings`.
.. hint:: If you have a standalone installation and your API returns
``https://dpaste-base-url.example.org`` as the domain, you need to adjust
the setting ``get_base_url`` property. See :ref:`settings`.
Third party API integration into editors
========================================
Third party API integration
===========================
subdpaste
a Sublime Editor plugin: https://github.com/bartTC/SubDpaste

5
docs/conf.py
View file

@ -82,11 +82,6 @@ try:
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = ["_themes", ]
html_theme_options = {
'logo_only': True,
'display_version': False,
}
html_logo = "docs/_static/logo.svg"
except ImportError:
html_theme = 'alabaster'

8
docs/index.rst
View file

@ -8,15 +8,11 @@ Documentation
.. toctree::
:maxdepth: 1
standalone_installation
project_installation
installation
testing
management_commands
settings
api
.. toctree::
:maxdepth: 2
changelog
.. _dpaste.de: https://dpaste.de/

139
docs/installation.rst Normal file
View file

@ -0,0 +1,139 @@
.. _installation:
============
Installation
============
There are various ways to install and deploy dpaste. See the guides below:
dpaste with Docker
==================
dpaste Docker images are available to pull from the `Docker Hub`_.
Quickstart to run a dpaste container image:
.. code:: bash
$ docker run --rm -p 8000:8000 barttc/dpaste:latest
The dpaste image serves the project using uWSGi and is ready for production-like
environments. However it's encouraged to use an external database to store the
data. See the example below for all available options, specifically
``DATABASE_URL``:
.. code:: bash
$ docker run --rm --name db1 --detach postgres:latest
$ docker run --rm -p 12345:12345 \
--link db1 \
-e DATABASE_URL=postgres://postgres@db1:5432/postgres \
-e DEBUG=True \
-e SECRET_KEY=very-secret-key \
-e PORT=12345 \
barttc/dpaste:latest
.. _Docker Hub: https://hub.docker.com/r/barttc/dpaste
Integration into an existing Django project
===========================================
Install the latest dpaste release in your environment. This will install all
necessary dependencies of dpaste as well:
.. code-block:: bash
$ pip install dpaste
Add ``dpaste.apps.dpasteAppConfig`` to your ``INSTALLED_APPS`` list:
.. code-block:: python
INSTALLED_APPS = (
'django.contrib.sessions',
# ...
'dpaste.apps.dpasteAppConfig',
)
Add ``dpaste`` and the (optiona) ``dpaste_api`` url patterns:
.. code-block:: python
urlpatterns = patterns('',
# ...
url(r'my-pastebin/', include('dpaste.urls.dpaste')),
url(r'my-pastebin/api/', include('dpaste.urls.dpaste_api')),
)
Finally, migrate the database schema:
.. code-block:: bash
$ manage.py migrate dpaste
dpaste with docker-compose for local development
================================================
The project's preferred way for local development is docker-compose:
.. code:: bash
$ docker-compose up
This will open the Django runserver on http://127.0.0.1:8000. Changes to the
code are automatically reflected in the Docker container and the runserver
will reload automatically.
Upon first run you will need to migrate the database. Do that in a separate
terminal window:
.. code:: bash
$ docker-compose run --rm app ./manage.py migrate
dpaste with virtualenv for local development
============================================
If you prefer the classic local installation using Virtualenv then you can
do so. There's no magic involved.
Example:
.. code:: bash
$ python3 -m venv .venv
$ source .venv/bin/activate
$ pip install -e .[dev]
$ ./manage.py migrate
$ ./manage.py runserver
CSS and Javascript development
==============================
Static files are stored in the ``client/`` directory and must get compiled
and compressed before being used on the website.
.. code:: bash
$ npm install
There are some helper scripts you can invoke with ``make``
make js
Compile only JS files.
make css
Compile only CSS files.
make css-watch
Same as ``build-css`` but it automatically watches for changes in the
CSS files and re-compiles it.
After compilation the CSS and JS files are stored in ``dpaste/static/``
where they are picked up by Django (and Django's collectstatic command).
.. note::
These files are not commited to the project repository, however they are
part of the pypi wheel package, since users couldn't compile those once
they are within Python's site-packages.

49
docs/project_installation.rst
View file

@ -1,49 +0,0 @@
.. _project_installation:
====================
Project Installation
====================
.. important:: This documentation describes the installation of dpaste
into an existing Django project. If you want to run the application
standalone, see :ref:`standalone_installation`.
.. note:: Misaka, the Markdown renderer used in dpaste may need "dev" packages
for compilation on Debian based Linux distributions. Install it with
``sudo apt install python3.6-dev``.
Install the latest dpaste release in your environment. This will install all
necessary dependencies of dpaste as well:
.. code-block:: bash
$ pip install dpaste
Add ``dpaste.apps.dpasteAppConfig`` to your ``INSTALLED_APPS`` list:
.. code-block:: python
INSTALLED_APPS = (
'django.contrib.sessions',
# ...
'dpaste.apps.dpasteAppConfig',
)
Add ``dpaste`` and the (optiona) ``dpaste_api`` url patterns:
.. code-block:: python
urlpatterns = patterns('',
# ...
url(r'my-pastebin/', include('dpaste.urls.dpaste')),
url(r'my-pastebin/api/', include('dpaste.urls.dpaste_api')),
)
Finally, migrate the database schema:
.. code-block:: bash
$ manage.py migrate dpaste

6
docs/settings.rst
View file

@ -1,8 +1,8 @@
.. _settings:
==========================
Settings and Configuration
==========================
========
Settings
========
When dpaste is installed as a standalone service or integrated into an existing
project there are various settings you can override to adjust dpaste's

114
docs/standalone_installation.rst
View file

@ -1,114 +0,0 @@
.. _standalone_installation:
==============================================
Standalone Installation (or local development)
==============================================
.. important:: This documentation describes the installation of dpaste
as a standalone project, primarily for local development. If you want
to integrate the application into your existing Django project, see
:ref:`project_installation`.
The project uses Docker for local development. Start it with:
.. code:: bash
$ make up
Or if you're more familiar with docker-compose
.. code:: bash
$ docker-compose run --rm app ./manage.py migrate
$ docker-compose up
This will open the Django runserver on http://127.0.0.1:8000. Changes to the
code are automatically reflected in the Docker container and the runserver
will reload automatically.
Local development using virtualenv
==================================
If you prefer the classic local installation using Virtualenv then you can
do so. There's nothing magic involved:
.. code:: bash
$ python3 -m venv .venv
$ source .venv/bin/activate
$ pip install -e .[dev]
CSS and Javascript development
==============================
Both [S]CSS and Javascript files need to be compiled and compressed.
Install the necessary node dependencies first:
.. code:: bash
$ npm install
There are some helper scripts you can invoke with ``make``
``npm js``
Compile only JS files.
``npm css``
Compile only CSS files.
``make css-watch``
Same as ``build-css`` but it automatically watches for changes in the
CSS files and re-compiles it.
``make docs``
Compile this documentation. The result will be in ``docs/_build/html``.
``make docs-watch``
Same as ``docs`` but it automatically watches for changes in the
documentation files and re-compiles the docs.
.. note:: See ``make help`` for the full and most recent list of
helper scripts.
Testing with Tox
================
dpaste is continuously tested online with Travis_. You can also run the test
suite locally with tox_. Tox automatically tests the project against multiple
Python and Django versions.
Similar to ``pipenv`` it's useful to have tox installed globally:
.. code-block:: bash
$ pip install tox
Then simply call it from the project directory.
.. code-block:: bash
$ cd dpaste/
$ tox
.. code-block:: text
:caption: Example tox output:
$ tox
py35-django-111 create: /tmp/tox/dpaste/py35-django-111
SKIPPED:InterpreterNotFound: python3.5
py36-django-111 create: /tmp/tox/dpaste/py36-django-111
py36-django-111 installdeps: django>=1.11,<1.12
py36-django-111 inst: /tmp/tox/dpaste/dist/dpaste-3.0a1.zip
...................
----------------------------------------------------------------------
Ran 48 tests in 1.724s
OK
SKIPPED: py35-django-111: InterpreterNotFound: python3.5
SKIPPED: py35-django-20: InterpreterNotFound: python3.5
py36-django-111: commands succeeded
py36-django-20: commands succeeded
congratulations :)
.. _Travis: https://travis-ci.org/bartTC/dpaste
.. _tox: http://tox.readthedocs.org/en/latest/

49
docs/testing.rst Normal file
View file

@ -0,0 +1,49 @@
.. _testing:
=======
Testing
=======
Testing with Tox
================
dpaste is continuously tested online with Travis_. You can also run the test
suite locally with tox_. Tox automatically tests the project against multiple
Python and Django versions.
.. code-block:: bash
$ pip install tox
Then simply call it from the project directory.
.. code-block:: bash
$ cd dpaste/
$ tox
.. code-block:: text
:caption: Example tox output:
$ tox
py35-django-111 create: /tmp/tox/dpaste/py35-django-111
SKIPPED:InterpreterNotFound: python3.5
py36-django-111 create: /tmp/tox/dpaste/py36-django-111
py36-django-111 installdeps: django>=1.11,<1.12
py36-django-111 inst: /tmp/tox/dpaste/dist/dpaste-3.0a1.zip
...................
----------------------------------------------------------------------
Ran 48 tests in 1.724s
OK
SKIPPED: py35-django-111: InterpreterNotFound: python3.5
SKIPPED: py35-django-20: InterpreterNotFound: python3.5
py36-django-111: commands succeeded
py36-django-20: commands succeeded
congratulations :)
.. _Travis: https://travis-ci.org/bartTC/dpaste
.. _tox: http://tox.readthedocs.org/en/latest/