Darren/dpaste
1
0
Fork 0
mirror of https://github.com/DarrenOfficial/dpaste.git synced 2024-11-15 08:02:54 +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 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, :statuscode 400: One of the above form options was invalid,
the response will contain a meaningful error message. the response will contain a meaningful error message.
.. hint:: If yuo have a standalone installation and your API returns .. hint:: If you have a standalone installation and your API returns
``https://dpaste.de/`` as the domain, you need to adjust the setting ``https://dpaste-base-url.example.org`` as the domain, you need to adjust
``BASE_URL`` property. See :ref:`settings`. the setting ``get_base_url`` property. See :ref:`settings`.
Third party API integration into editors Third party API integration
======================================== ===========================
subdpaste subdpaste
a Sublime Editor plugin: https://github.com/bartTC/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 import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme" html_theme = "sphinx_rtd_theme"
html_theme_path = ["_themes", ] html_theme_path = ["_themes", ]
html_theme_options = {
'logo_only': True,
'display_version': False,
}
html_logo = "docs/_static/logo.svg"
except ImportError: except ImportError:
html_theme = 'alabaster' html_theme = 'alabaster'

8
docs/index.rst
View file

@ -8,15 +8,11 @@ Documentation
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1
standalone_installation installation
project_installation testing
management_commands management_commands
settings settings
api api
.. toctree::
:maxdepth: 2
changelog changelog
.. _dpaste.de: https://dpaste.de/ .. _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:
========================== ========
Settings and Configuration Settings
========================== ========
When dpaste is installed as a standalone service or integrated into an existing 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 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/