Skip to content
Snippets Groups Projects
Commit 79c2dbfc authored by Erwan Rouchet's avatar Erwan Rouchet
Browse files

Update docs

parent c4421096
No related branches found
No related tags found
No related merge requests found
Pipeline #28111 passed
Stage: test
Stage: deploy
Hide whitespace changes
Inline Side-by-side
.gitignore
+ 2
− 1
View file @ 79c2dbfc
......@@ -19,8 +19,9 @@ MANIFEST
# Pytest
.pytest_cache/
# Sphinx
# Docs
docs/_build/
public/
# Editors
.vscode/
......
.gitlab-ci.yml
+ 1
− 4
View file @ 79c2dbfc
......@@ -70,8 +70,5 @@ pages:
- public
before_script:
- pip install .
- pip install sphinx
script:
- cd docs
- make html
- mv _build/html ../public
- make docs
Makefile 0 → 100644
+ 5
− 0
View file @ 79c2dbfc
docs:
mkdir -p public
apistar docs --path arkindex/schema.yml --theme redoc --output-dir public
# Use relative links for static files
sed -i "s/\(['\"]\)\/\(js\|css\|schema\)/\\1\\2/g" public/index.html
README.md deleted 100644 → 0
+ 0
− 3
View file @ c4421096
# Arkindex API Client
An API client to access Arkindex servers. [Full documentation](https://arkindex.gitlab.io/api-client/)
docs/index.rst → README.rst
+ 7
− 33
View file @ 79c2dbfc
Arkindex API Client
===================
:ref:`genindex` - :ref:`modindex` - :ref:`search` - `API documentation <apistar/index.html>`_
**API documentation available at https://arkindex.gitlab.io/api-client/**
``arkindex-client`` provides an API client to interact with Arkindex servers.
......@@ -21,7 +21,7 @@ Usage
-----
To create a client and login using an email/password combo,
use the :meth:`ArkindexClient.login` helper method:
use the ``ArkindexClient.login`` helper method:
.. code:: python
......@@ -57,8 +57,8 @@ Dealing with pagination
^^^^^^^^^^^^^^^^^^^^^^^
The Arkindex client adds another helper method for paginated endpoints that
deals with pagination for you: :meth:`ArkindexClient.paginate`. This method
returns a :class:`ResponsePaginator` instance, which is a classic Python
deals with pagination for you: ``ArkindexClient.paginate``. This method
returns a ``ResponsePaginator`` instance, which is a classic Python
iterator that does not perform any actual requests until absolutely needed:
that is, until the next page must be loaded.
......@@ -67,11 +67,9 @@ that is, until the next page must be loaded.
for page in cli.paginate('ListCorpusPages', id=corpus['id']):
print(page['display_name'])
.. warning:
Using the ``list`` method on a :class:`ResponsePaginator` may load dozens
of pages at once and cause a big load on the server. You can use ``len`` to
get the total item count before spamming a server.
**Warning:** Using ``list`` on a ``ResponsePaginator`` may load dozens
of pages at once and cause a big load on the server. You can use ``len`` to
get the total item count before spamming a server.
Using another server
^^^^^^^^^^^^^^^^^^^^
......@@ -134,27 +132,3 @@ Download full logs for each Ponos task in a workflow
for task in workflow['tasks']:
with open(task['id'] + '.txt', 'w') as f:
f.write(cli.request('RetrieveTaskLog', id=task['id']))
Package reference
-----------------
The Arkindex client subclasses the `APIStar client`_ to add helper functions
on top of an `OpenAPI`_ schema found at ``arkindex/schema.yml``.
.. _APIStar client: http://docs.apistar.com/client-library/
.. _OpenAPI: https://www.openapis.org/
API client
^^^^^^^^^^
.. autoclass:: arkindex.client.ArkindexClient
:members:
Helper classes
^^^^^^^^^^^^^^
.. autoclass:: arkindex.pagination.ResponsePaginator
:members:
.. autoclass:: arkindex.auth.TokenSessionAuthentication
:members:
docs/Makefile deleted 100644 → 0
+ 0
− 28
View file @ c4421096
# Minimal makefile for Sphinx documentation
ROOT_DIR:=$(shell dirname $(realpath $(lastword $(MAKEFILE_LIST))))
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
html: Makefile
mkdir -p "$(BUILDDIR)/html"
apistar docs --path ../arkindex/schema.yml --theme swaggerui --output-dir $(BUILDDIR)/html/swagger
apistar docs --path ../arkindex/schema.yml --theme redoc --output-dir $(BUILDDIR)/html/redoc
apistar docs --path ../arkindex/schema.yml --theme apistar --output-dir $(BUILDDIR)/html/apistar
# Use relative links for static files
sed -i "s/\(['\"]\)\/\(js\|css\|schema\)/\\1\\2/g" _build/html/swagger/index.html _build/html/redoc/index.html _build/html/apistar/index.html
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
docs/conf.py deleted 100644 → 0
+ 0
− 192
View file @ c4421096
# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# http://www.sphinx-doc.org/en/master/config
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
sys.path.insert(0, os.path.abspath('..'))
# -- Project information -----------------------------------------------------
project = 'Arkindex Client'
copyright = '2019, Teklia'
author = 'Teklia'
# The short X.Y version
version = ''
# The full version, including alpha/beta/rc tags
release = open('../VERSION').read().strip()
# -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.viewcode',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = None
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
html_theme_options = {
'fixed_sidebar': 'true',
'extra_nav_links': {
'API docs': 'apistar/index.html',
'Swagger API docs': 'swagger/index.html',
'Redoc API docs': 'redoc/index.html',
}
}
# 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,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself. Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
html_sidebars = {
'**': [
'about.html',
'navigation.html',
'relations.html',
'searchbox.html',
]
}
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'ArkindexClientdoc'
# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'ArkindexClient.tex', 'Arkindex Client Documentation',
'Teklia', 'manual'),
]
# -- Options for manual page output ------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'arkindexclient', 'Arkindex Client Documentation',
[author], 1)
]
# -- Options for Texinfo output ----------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'ArkindexClient', 'Arkindex Client Documentation',
author, 'ArkindexClient', 'One line description of project.',
'Miscellaneous'),
]
# -- Options for Epub output -------------------------------------------------
# Bibliographic Dublin Core info.
epub_title = project
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#
# epub_identifier = ''
# A unique identification for the text.
#
# epub_uid = ''
# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']
# -- Extension configuration -------------------------------------------------
setup.py
+ 3
− 3
View file @ 79c2dbfc
......@@ -14,7 +14,7 @@ setup(
exclude=["*.tests", "*.tests.*", "tests.*", "tests"],
),
package_data={
'': ['*.md', 'LICENSE', 'README'],
'': ['*.rst', 'LICENSE', 'README'],
},
install_requires=read_requirements('requirements-frozen.txt'),
python_requires=">=3.6",
......@@ -23,8 +23,8 @@ setup(
},
license='MIT',
description="API client for the Arkindex project",
long_description=open('README.md').read(),
long_description_content_type='text/markdown',
long_description=open('README.rst').read(),
long_description_content_type='text/x-rst',
keywords="api client arkindex",
url="https://gitlab.com/arkindex/api-client",
classifiers=[
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment