summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorLars-Dominik Braun <lars@6xq.net>2019-07-04 13:53:30 +0200
committerLars-Dominik Braun <lars@6xq.net>2019-07-04 13:53:30 +0200
commit799c79638b9bdebd7d04c524a2dd6e8779057679 (patch)
tree5ab5f8250cc771838e4f9de2fe3ea2d9411fd78b /doc
parente7eb6fcd4781a907bf698a88df9cb34b5b31c369 (diff)
downloadcrocoite-799c79638b9bdebd7d04c524a2dd6e8779057679.tar.gz
crocoite-799c79638b9bdebd7d04c524a2dd6e8779057679.tar.bz2
crocoite-799c79638b9bdebd7d04c524a2dd6e8779057679.zip
Update documentation
Re-arrange stuff, add release guide. Needs a lot more work though.
Diffstat (limited to 'doc')
-rw-r--r--doc/conf.py14
-rw-r--r--doc/develop.rst24
-rw-r--r--doc/index.rst7
-rw-r--r--doc/install.rst47
-rw-r--r--doc/usage.rst14
5 files changed, 47 insertions, 59 deletions
diff --git a/doc/conf.py b/doc/conf.py
index 746dbc6..9dbeabe 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -82,7 +82,15 @@ html_theme = 'alabaster'
# further. For a list of options available for each theme, see the
# documentation.
#
-# html_theme_options = {}
+html_theme_options = {
+ "description": "Preservation for the modern web",
+ "github_user": "PromyLOPh",
+ "github_repo": "crocoite",
+ "travis_button": True,
+ "github_button": True,
+ "codecov_button": True,
+ "fixed_sidebar": True,
+}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
@@ -97,7 +105,9 @@ html_static_path = ['_static']
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
-# html_sidebars = {}
+html_sidebars = {
+ '**': ['about.html', 'navigation.html', 'searchbox.html'],
+}
# -- Options for HTMLHelp output ---------------------------------------------
diff --git a/doc/develop.rst b/doc/develop.rst
index 0113c92..8a8e8bd 100644
--- a/doc/develop.rst
+++ b/doc/develop.rst
@@ -15,3 +15,27 @@ console.
.. _devtools module: crocoite/devtools.py
+Release guide
+^^^^^^^^^^^^^
+
+crocoite uses `semantic versioning`_. To create a new release, bump the version
+number in ``setup.py`` according to the linked guide, create distribution
+packages::
+
+ python setup.py sdist bdist_wheel
+
+Verify them::
+
+ twine check dist/*
+
+Try to install and use them in a separate sandbox. And finally sign and upload
+a new version to pypi_::
+
+ gpg --detach-sign --armor dist/*.tar.gz
+ twine upload dist/*
+
+Then update the documentation using ``sphing-doc`` and upload it as well.
+
+.. _semantic versioning: https://semver.org/spec/v2.0.0.html
+.. _pypi: https://pypi.org
+
diff --git a/doc/index.rst b/doc/index.rst
index d62c7e1..39c2f73 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -4,19 +4,12 @@ crocoite
Preservation for the modern web, powered by `headless Google
Chrome`_.
-.. image:: https://travis-ci.org/PromyLOPh/crocoite.svg?branch=master
- :target: https://travis-ci.org/PromyLOPh/crocoite
-
-.. image:: https://codecov.io/gh/PromyLOPh/crocoite/branch/master/graph/badge.svg
- :target: https://codecov.io/gh/PromyLOPh/crocoite
-
.. _headless Google Chrome: https://developers.google.com/web/updates/2017/04/headless-chrome
.. toctree::
:maxdepth: 1
:hidden:
- install.rst
usage.rst
rationale.rst
develop.rst
diff --git a/doc/install.rst b/doc/install.rst
deleted file mode 100644
index 5e76956..0000000
--- a/doc/install.rst
+++ /dev/null
@@ -1,47 +0,0 @@
-Installation
-------------
-
-These dependencies must be present to run crocoite:
-
-- Python ≥3.6
-- PyYAML_
-- aiohttp_
-- websockets_
-- warcio_
-- html5lib_
-- yarl_
-- multidict_
-- bottom_ (IRC client)
-- `Google Chrome`_
-
-.. _PyYAML: https://pyyaml.org/wiki/PyYAML
-.. _aiohttp: https://aiohttp.readthedocs.io/
-.. _websockets: https://websockets.readthedocs.io/
-.. _warcio: https://github.com/webrecorder/warcio
-.. _html5lib: https://github.com/html5lib/html5lib-python
-.. _bottom: https://github.com/numberoverzero/bottom
-.. _Google Chrome: https://www.google.com/chrome/
-.. _yarl: https://yarl.readthedocs.io/
-.. _multidict: https://multidict.readthedocs.io/
-
-The following commands clone the repository from GitHub_, set up a virtual
-environment and install crocoite:
-
-.. _GitHub: https://github.com/PromyLOPh/crocoite
-
-.. code:: bash
-
- git clone https://github.com/PromyLOPh/crocoite.git
- cd crocoite
- virtualenv -p python3 sandbox
- source sandbox/bin/activate
- pip install .
-
-It is recommended to install at least Micrsoft’s Corefonts_ as well as DejaVu_,
-Liberation_ or a similar font family covering a wide range of character sets.
-Otherwise page screenshots may be unusable due to missing glyphs.
-
-.. _Corefonts: http://corefonts.sourceforge.net/
-.. _DejaVu: https://dejavu-fonts.github.io/
-.. _Liberation: https://pagure.io/liberation-fonts
-
diff --git a/doc/usage.rst b/doc/usage.rst
index a3c2cc7..b070f5c 100644
--- a/doc/usage.rst
+++ b/doc/usage.rst
@@ -1,18 +1,26 @@
Usage
-----
-One-shot command line interface and pywb_ playback:
+Quick start using pywb_, expects Google Chrome to be installed already:
.. code:: bash
- pip install pywb
+ pip install crocoite pywb
crocoite http://example.com/ example.com.warc.gz
- rm -rf collections && wb-manager init test && wb-manager add test example.com.warc.gz
+ wb-manager init test && wb-manager add test example.com.warc.gz
wayback &
$BROWSER http://localhost:8080
.. _pywb: https://github.com/ikreymer/pywb
+It is recommended to install at least Micrsoft’s Corefonts_ as well as DejaVu_,
+Liberation_ or a similar font family covering a wide range of character sets.
+Otherwise page screenshots may be unusable due to missing glyphs.
+
+.. _Corefonts: http://corefonts.sourceforge.net/
+.. _DejaVu: https://dejavu-fonts.github.io/
+.. _Liberation: https://pagure.io/liberation-fonts
+
IRC bot
^^^^^^^