mirror of
https://github.com/DarrenOfficial/dpaste.git
synced 2024-11-15 08:02:54 +11:00
Docs Update
This commit is contained in:
parent
2fdb6f44f8
commit
5d1b59ca6e
8 changed files with 203 additions and 184 deletions
17
docs/api.rst
17
docs/api.rst
|
@ -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
|
||||
|
|
|
@ -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,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
139
docs/installation.rst
Normal 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.
|
||||
|
|
@ -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
|
||||
|
||||
|
|
@ -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
|
||||
|
|
|
@ -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
49
docs/testing.rst
Normal 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/
|
Loading…
Reference in a new issue