diff --git a/README.md b/README.rst similarity index 93% rename from README.md rename to README.rst index bf4ef79..62509b5 100644 --- a/README.md +++ b/README.rst @@ -1,66 +1,71 @@ -swh-core -======== +.. _swh-core: + +Software Heritage - Core foundations +==================================== + +Low-level utilities and helpers used by almost all other modules in the stack. core library for swh's modules: + - config parser - hash computations - serialization - logging mechanism - database connection - http-based RPC client/server Development ----------- We strongly recommend you to use a [virtualenv][1] if you want to run tests or hack the code. To set up your development environment: ``` (swh) user@host:~/swh-environment/swh-core$ pip install -e .[testing] ``` This will install every Python package needed to run this package's tests. Unit tests can be executed using [pytest][2] or [tox][3]. ``` (swh) user@host:~/swh-environment/swh-core$ pytest ============================== test session starts ============================== platform linux -- Python 3.7.3, pytest-3.10.1, py-1.8.0, pluggy-0.12.0 hypothesis profile 'default' -> database=DirectoryBasedExampleDatabase('/home/ddouard/src/swh-environment/swh-core/.hypothesis/examples') rootdir: /home/ddouard/src/swh-environment/swh-core, inifile: pytest.ini plugins: requests-mock-1.6.0, hypothesis-4.26.4, celery-4.3.0, postgresql-1.4.1 collected 89 items swh/core/api/tests/test_api.py .. [ 2%] swh/core/api/tests/test_async.py .... [ 6%] swh/core/api/tests/test_serializers.py ..... [ 12%] swh/core/db/tests/test_db.py .... [ 16%] swh/core/tests/test_cli.py ...... [ 23%] swh/core/tests/test_config.py .............. [ 39%] swh/core/tests/test_statsd.py ........................................... [ 87%] .... [ 92%] swh/core/tests/test_utils.py ....... [100%] ===================== 89 passed, 9 warnings in 6.94 seconds ===================== ``` Note: this git repository uses [pre-commit][4] hooks to ensure better and more consistent code. It should already be installed in your virtualenv (if not, just type `pip install pre-commit`). Make sure to activate it in your local copy of the git repository: ``` (swh) user@host:~/swh-environment/swh-core$ pre-commit install pre-commit installed at .git/hooks/pre-commit ``` Please read the [developer setup manual][5] for more information on how to hack on Software Heritage. [1]: https://virtualenv.pypa.io [2]: https://docs.pytest.org [3]: https://tox.readthedocs.io [4]: https://pre-commit.com [5]: https://docs.softwareheritage.org/devel/developer-setup.html diff --git a/docs/README.rst b/docs/README.rst new file mode 120000 index 0000000..89a0106 --- /dev/null +++ b/docs/README.rst @@ -0,0 +1 @@ +../README.rst \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index efdf06b..a3e00dc 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,16 +1,10 @@ -.. _swh-core: - -Software Heritage - Core foundations -==================================== - -Low-level utilities and helpers used by almost all other modules in the stack. - +.. include:: README.rst Reference Documentation ----------------------- .. toctree:: :maxdepth: 2 cli /apidoc/swh.core diff --git a/setup.py b/setup.py index 4f0555e..27766b9 100755 --- a/setup.py +++ b/setup.py @@ -1,89 +1,89 @@ #!/usr/bin/env python3 # Copyright (C) 2015-2018 The Software Heritage developers # See the AUTHORS file at the top-level directory of this distribution # License: GNU General Public License version 3, or any later version # See top-level LICENSE file for more information from io import open import os from os import path from setuptools import find_packages, setup here = path.abspath(path.dirname(__file__)) # Get the long description from the README file -with open(path.join(here, "README.md"), encoding="utf-8") as f: +with open(path.join(here, "README.rst"), encoding="utf-8") as f: long_description = f.read() def parse_requirements(*names): requirements = [] for name in names: if name: reqf = "requirements-%s.txt" % name else: reqf = "requirements.txt" if not os.path.exists(reqf): return requirements with open(reqf) as f: for line in f.readlines(): line = line.strip() if not line or line.startswith("#"): continue requirements.append(line) return requirements setup( name="swh.core", description="Software Heritage core utilities", long_description=long_description, - long_description_content_type="text/markdown", + long_description_content_type="text/x-rst", python_requires=">=3.7", author="Software Heritage developers", author_email="swh-devel@inria.fr", url="https://forge.softwareheritage.org/diffusion/DCORE/", packages=find_packages(), py_modules=["pytest_swh_core"], scripts=[], install_requires=parse_requirements(None, "swh"), setup_requires=["setuptools-scm"], use_scm_version=True, extras_require={ "testing-core": parse_requirements("test"), "logging": parse_requirements("logging"), "db": parse_requirements("db", "db-pytestplugin"), "testing-db": parse_requirements("test-db"), "http": parse_requirements("http"), # kitchen sink, please do not use "testing": parse_requirements( "test", "test-db", "db", "db-pytestplugin", "http", "logging" ), }, include_package_data=True, entry_points=""" [console_scripts] swh=swh.core.cli:main swh-db-init=swh.core.cli.db:db_init [swh.cli.subcommands] db=swh.core.cli.db [pytest11] pytest_swh_core = swh.core.pytest_plugin """, classifiers=[ "Programming Language :: Python :: 3", "Intended Audience :: Developers", "License :: OSI Approved :: GNU General Public License v3 (GPLv3)", "Operating System :: OS Independent", "Development Status :: 5 - Production/Stable", ], project_urls={ "Bug Reports": "https://forge.softwareheritage.org/maniphest", "Funding": "https://www.softwareheritage.org/donate", "Source": "https://forge.softwareheritage.org/source/swh-core", "Documentation": "https://docs.softwareheritage.org/devel/swh-core/", }, )