From 5d1b59ca6ee99e816b81985c1bd04925439533fd Mon Sep 17 00:00:00 2001 From: Martin Mahner Date: Sun, 8 Dec 2019 19:39:43 +0100 Subject: [PATCH] Docs Update --- docs/api.rst | 17 ++-- docs/conf.py | 5 -- docs/index.rst | 8 +- docs/installation.rst | 139 +++++++++++++++++++++++++++++++ docs/project_installation.rst | 49 ----------- docs/settings.rst | 6 +- docs/standalone_installation.rst | 114 ------------------------- docs/testing.rst | 49 +++++++++++ 8 files changed, 203 insertions(+), 184 deletions(-) create mode 100644 docs/installation.rst delete mode 100644 docs/standalone_installation.rst create mode 100644 docs/testing.rst diff --git a/docs/api.rst b/docs/api.rst index 37fffb0..1fea874 100644 --- a/docs/api.rst +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index 61b7c5e..e36d914 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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' diff --git a/docs/index.rst b/docs/index.rst index 82e274a..ecf95c0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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/ diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..15a65de --- /dev/null +++ b/docs/installation.rst @@ -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. + diff --git a/docs/project_installation.rst b/docs/project_installation.rst index a6c3f5b..e69de29 100644 --- a/docs/project_installation.rst +++ b/docs/project_installation.rst @@ -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 - - diff --git a/docs/settings.rst b/docs/settings.rst index 210edcc..fa61204 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -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 diff --git a/docs/standalone_installation.rst b/docs/standalone_installation.rst deleted file mode 100644 index 20ea37a..0000000 --- a/docs/standalone_installation.rst +++ /dev/null @@ -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/ diff --git a/docs/testing.rst b/docs/testing.rst new file mode 100644 index 0000000..76ddd37 --- /dev/null +++ b/docs/testing.rst @@ -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/