From 799c79638b9bdebd7d04c524a2dd6e8779057679 Mon Sep 17 00:00:00 2001 From: Lars-Dominik Braun Date: Thu, 4 Jul 2019 13:53:30 +0200 Subject: Update documentation Re-arrange stuff, add release guide. Needs a lot more work though. --- README.rst | 16 +++++++++++++++- doc/conf.py | 14 ++++++++++++-- doc/develop.rst | 24 ++++++++++++++++++++++++ doc/index.rst | 7 ------- doc/install.rst | 47 ----------------------------------------------- doc/usage.rst | 14 +++++++++++--- 6 files changed, 62 insertions(+), 60 deletions(-) mode change 120000 => 100644 README.rst delete mode 100644 doc/install.rst diff --git a/README.rst b/README.rst deleted file mode 120000 index 176d9c2..0000000 --- a/README.rst +++ /dev/null @@ -1 +0,0 @@ -doc/index.rst \ No newline at end of file diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..b1d9e5b --- /dev/null +++ b/README.rst @@ -0,0 +1,15 @@ +crocoite +======== + +.. code:: bash + + pip install crocoite pywb + crocoite http://example.com/ example.com.warc.gz + wb-manager init test && wb-manager add test example.com.warc.gz + wayback & + $BROWSER http://localhost:8080 + +See documentation_ for more information. + +.. _documentation: https://6xq.net/crocoite/ + 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 ^^^^^^^ -- cgit v1.2.3