diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 00000000..231f82c3 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,15 @@ +.git +*.gitignore + +*.mo +*.pyc +*.swp +*.swo +*.~ + +.dockerignore +Dockerfile +docker-compose.yml +docker-compose-dev.yml + +Procfile* diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 00000000..22371b92 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,41 @@ +# -*- coding: utf-8 -*- +# +# Copyright (C) 2020 CERN. +# +# Invenio-Vocabularies is free software; you can redistribute it and/or +# modify it under the terms of the MIT License; see LICENSE file for more +# details. + +root = true + +[*] +indent_style = space +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true +charset = utf-8 + +# Python files +[*.py] +indent_size = 4 +# isort plugin configuration +known_first_party = invenio_vocabularies +multi_line_output = 2 +default_section = THIRDPARTY +skip = .eggs + +# RST files (used by sphinx) +[*.rst] +indent_size = 4 + +# CSS, HTML, JS, JSON, YML +[*.{css,html,js,json,yml}] +indent_size = 2 + +# Matches the exact files either package.json or .travis.yml +[{package.json,.travis.yml}] +indent_size = 2 + +# Dockerfile +[Dockerfile] +indent_size = 4 diff --git a/.github/workflows/pypi-publish.yml b/.github/workflows/pypi-publish.yml new file mode 100644 index 00000000..5168e16e --- /dev/null +++ b/.github/workflows/pypi-publish.yml @@ -0,0 +1,28 @@ +on: + push: + tags: + - v* + +jobs: + build-n-publish: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Set up Python 3.7 + uses: actions/setup-python@v2 + with: + python-version: 3.7 + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install setuptools wheel + - name: Build package + run: | + python setup.py compile_catalog sdist bdist_wheel + - name: pypi-publish + uses: pypa/gh-action-pypi-publish@v1.3.1 + with: + user: __token__ + + password: ${{ secrets.pypi_token }} + diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml new file mode 100644 index 00000000..cab70dd2 --- /dev/null +++ b/.github/workflows/tests.yml @@ -0,0 +1,92 @@ +name: CI + +on: + push: + branches: master + pull_request: + branches: master + schedule: + # * is a special character in YAML so you have to quote this string + - cron: '0 3 * * 6' + workflow_dispatch: + inputs: + reason: + description: 'Reason' + required: false + default: 'Manual trigger' + +jobs: + Tests: + runs-on: ubuntu-20.04 + strategy: + matrix: + python-version: [3.6, 3.7, 3.8] + # You can add more combinations e.g. dev requirements or MySQL by adding + # a new item to this list. Add its corresponding definition below. + # EXTRAS and REQUIREMENTS_LEVEL are always needed. + services: [release, lowest, devel] + include: + - services: release + SQLALCHEMY_DATABASE_URI: "postgresql+psycopg2://invenio:invenio@localhost:5432/invenio" + POSTGRESQL_VERSION: POSTGRESQL_12_LATEST + ES_VERSION: "ES_7_LATEST" + EXTRAS: "all,postgresql,elasticsearch7" + REQUIREMENTS_LEVEL: "pypi" + - services: lowest + SQLALCHEMY_DATABASE_URI: "postgresql+psycopg2://invenio:invenio@localhost:5432/invenio" + POSTGRESQL_VERSION: POSTGRESQL_9_LATEST + ES_VERSION: "ES_6_LATEST" + EXTRAS: "all,postgresql,elasticsearch6" + REQUIREMENTS_LEVEL: "min" + - services: devel + SQLALCHEMY_DATABASE_URI: "postgresql+psycopg2://invenio:invenio@localhost:5432/invenio" + POSTGRESQL_VERSION: POSTGRESQL_12_LATEST + ES_VERSION: "ES_7_LATEST" + EXTRAS: "all,postgresql,elasticsearch7" + REQUIREMENTS_LEVEL: "dev" + + env: + SQLALCHEMY_DATABASE_URI: ${{matrix.SQLALCHEMY_DATABASE_URI}} + POSTGRESQL_VERSION: ${{matrix.POSTGRESQL_VERSION}} + ES_VERSION: ${{matrix.ES_VERSION}} + + steps: + - name: Checkout + uses: actions/checkout@v2 + + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v2 + with: + python-version: ${{ matrix.python-version }} + + - name: Generate dependencies + if: ${{ matrix.REQUIREMENTS_LEVEL != 'dev' }} + run: | + python -m pip install --upgrade pip setuptools py wheel requirements-builder + requirements-builder -e ${{ matrix.EXTRAS }} --level=${{ matrix.REQUIREMENTS_LEVEL }} setup.py > .${{ matrix.REQUIREMENTS_LEVEL }}-${{ matrix.python-version }}-requirements.txt + + - name: Generate dependencies devel + if: ${{ matrix.REQUIREMENTS_LEVEL == 'dev' }} + run: | + python -m pip install --upgrade pip setuptools py wheel requirements-builder + requirements-builder -e ${{ matrix.EXTRAS }} --level=${{ matrix.REQUIREMENTS_LEVEL }} --req requirements-devel.txt setup.py > .${{ matrix.REQUIREMENTS_LEVEL }}-${{ matrix.python-version }}-requirements.txt + + - name: Cache pip + uses: actions/cache@v2 + with: + path: ~/.cache/pip + key: ${{ runner.os }}-pip-${{ hashFiles('.${{ matrix.REQUIREMENTS_LEVEL }}-${{ matrix.python-version }}-requirements.txt') }} + + - name: Install dependencies + run: | + pip install -r .${{matrix.REQUIREMENTS_LEVEL}}-${{ matrix.python-version }}-requirements.txt + pip install -e .[all] + pip freeze + docker --version + docker-compose --version + + - name: Run tests + # You must change the ignore command for the manifest check. + # Remove `.travis-*` and add `.*-requirements.txt` + run: | + ./run-tests.sh diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..f2229c3b --- /dev/null +++ b/.gitignore @@ -0,0 +1,62 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] + +# Idea software family +.idea/ + +# C extensions +*.so + +# Distribution / packaging +.Python +env/ +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +*.egg-info/ +.installed.cfg +*.egg + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*,cover + +# Translations +*.mo + +# Django stuff: +*.log + +# Sphinx documentation +docs/_build/ + +# PyBuilder +target/ + +# Vim swapfiles +.*.sw? diff --git a/.tx/config b/.tx/config new file mode 100644 index 00000000..7d22cd68 --- /dev/null +++ b/.tx/config @@ -0,0 +1,33 @@ +# -*- coding: utf-8 -*- +# +# Copyright (C) 2020 CERN. +# +# Invenio-Vocabularies is free software; you can redistribute it and/or +# modify it under the terms of the MIT License; see LICENSE file for more +# details. + +# TODO: Transifex integration +# +# 1) Create message catalog: +# $ python setup.py extract_messages +# $ python setup.py init_catalog -l +# $ python setup.py compile_catalog +# 2) Ensure project has been created on Transifex under the inveniosoftware +# organisation. +# 3) Install the transifex-client +# $ pip install transifex-client +# 4) Push source (.pot) and translations (.po) to Transifex +# $ tx push -s -t +# 5) Pull translations for a single language from Transifex +# $ tx pull -l +# 6) Pull translations for all languages from Transifex +# $ tx pull -a + +[main] +host = https://www.transifex.com + +[invenio.invenio-vocabularies-messages] +file_filter = invenio_vocabularies/translations//LC_MESSAGES/messages.po +source_file = invenio_vocabularies/translations/messages.pot +source_lang = en +type = PO diff --git a/AUTHORS.rst b/AUTHORS.rst new file mode 100644 index 00000000..06efaa09 --- /dev/null +++ b/AUTHORS.rst @@ -0,0 +1,13 @@ +.. + Copyright (C) 2020 CERN. + + Invenio-Vocabularies is free software; you can redistribute it and/or + modify it under the terms of the MIT License; see LICENSE file for more + details. + +Authors +======= + +Invenio module for managing vocabularies. + +- CERN diff --git a/CHANGES.rst b/CHANGES.rst new file mode 100644 index 00000000..f9b9319b --- /dev/null +++ b/CHANGES.rst @@ -0,0 +1,13 @@ +.. + Copyright (C) 2020 CERN. + + Invenio-Vocabularies is free software; you can redistribute it and/or + modify it under the terms of the MIT License; see LICENSE file for more + details. + +Changes +======= + +Version 0.1.0 (released TBD) + +- Initial public release. diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 00000000..0b6c8898 --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,118 @@ +Contributing +============ + +Contributions are welcome, and they are greatly appreciated! Every +little bit helps, and credit will always be given. + +Types of Contributions +---------------------- + +Report Bugs +~~~~~~~~~~~ + +Report bugs at https://github.com/inveniosoftware/invenio-vocabularies/issues. + +If you are reporting a bug, please include: + +* Your operating system name and version. +* Any details about your local setup that might be helpful in troubleshooting. +* Detailed steps to reproduce the bug. + +Fix Bugs +~~~~~~~~ + +Look through the GitHub issues for bugs. Anything tagged with "bug" +is open to whoever wants to implement it. + +Implement Features +~~~~~~~~~~~~~~~~~~ + +Look through the GitHub issues for features. Anything tagged with "feature" +is open to whoever wants to implement it. + +Write Documentation +~~~~~~~~~~~~~~~~~~~ + +Invenio-Vocabularies could always use more documentation, whether as part of the +official Invenio-Vocabularies docs, in docstrings, or even on the web in blog posts, +articles, and such. + +Submit Feedback +~~~~~~~~~~~~~~~ + +The best way to send feedback is to file an issue at +https://github.com/inveniosoftware/invenio-vocabularies/issues. + +If you are proposing a feature: + +* Explain in detail how it would work. +* Keep the scope as narrow as possible, to make it easier to implement. +* Remember that this is a volunteer-driven project, and that contributions + are welcome :) + +Get Started! +------------ + +Ready to contribute? Here's how to set up `invenio-vocabularies` for local development. + +1. Fork the `inveniosoftware/invenio-vocabularies` repo on GitHub. +2. Clone your fork locally: + + .. code-block:: console + + $ git clone git@github.com:your_name_here/invenio-vocabularies.git + +3. Install your local copy into a virtualenv. Assuming you have + virtualenvwrapper installed, this is how you set up your fork for local + development: + + .. code-block:: console + + $ mkvirtualenv invenio-vocabularies + $ cd invenio-vocabularies/ + $ pip install -e .[all] + +4. Create a branch for local development: + + .. code-block:: console + + $ git checkout -b name-of-your-bugfix-or-feature + + Now you can make your changes locally. + +5. When you're done making changes, check that your changes pass tests: + + .. code-block:: console + + $ ./run-tests.sh + + The tests will provide you with test coverage and also check PEP8 + (code style), PEP257 (documentation), flake8 as well as build the Sphinx + documentation and run doctests. + +6. Commit your changes and push your branch to GitHub: + + .. code-block:: console + + $ git add . + $ git commit -s + -m "component: title without verbs" + -m "* NEW Adds your new feature." + -m "* FIX Fixes an existing issue." + -m "* BETTER Improves and existing feature." + -m "* Changes something that should not be visible in release notes." + $ git push origin name-of-your-bugfix-or-feature + +7. Submit a pull request through the GitHub website. + +Pull Request Guidelines +----------------------- + +Before you submit a pull request, check that it meets these guidelines: + +1. The pull request should include tests and must not decrease test coverage. +2. If the pull request adds functionality, the docs should be updated. Put + your new functionality into a function with a docstring. +3. The pull request should work for Python 2.7, 3.5 and 3.6. Check + https://travis-ci.org/inveniosoftware/invenio-vocabularies/pull_requests + and make sure that the tests pass for all supported Python versions. diff --git a/INSTALL.rst b/INSTALL.rst new file mode 100644 index 00000000..edabb551 --- /dev/null +++ b/INSTALL.rst @@ -0,0 +1,8 @@ +Installation +============ + +Invenio-Vocabularies is on PyPI so all you need is: + +.. code-block:: console + + $ pip install invenio-vocabularies diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000..51fdb304 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (C) 2020 CERN. + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies +of the Software, and to permit persons to whom the Software is furnished to do +so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/MANIFEST.in b/MANIFEST.in new file mode 100644 index 00000000..3d000bbc --- /dev/null +++ b/MANIFEST.in @@ -0,0 +1,22 @@ +# -*- coding: utf-8 -*- +# +# Copyright (C) 2020 CERN. +# +# Invenio-Vocabularies is free software; you can redistribute it and/or +# modify it under the terms of the MIT License; see LICENSE file for more +# details. + +# TODO: Generate this manifest file by running the following commands: +# (please sort the lines in this file after running below commands) +# +# git init +# git add -A +# pip install -e .[all] +# check-manifest -u + +include .dockerignore +include .editorconfig +include .tx/config +prune docs/_build +recursive-include .github/workflows *.yml +recursive-include invenio_vocabularies/translations *.po *.pot *.mo diff --git a/README.rst b/README.rst new file mode 100644 index 00000000..8df13083 --- /dev/null +++ b/README.rst @@ -0,0 +1,32 @@ +.. + Copyright (C) 2020 CERN. + + Invenio-Vocabularies is free software; you can redistribute it and/or + modify it under the terms of the MIT License; see LICENSE file for more + details. + +====================== + Invenio-Vocabularies +====================== + +.. image:: https://github.com/inveniosoftware/invenio-vocabularies/workflows/CI/badge.svg + :target: https://github.com/inveniosoftware/invenio-vocabularies/actions?query=workflow%3ACI + +.. image:: https://img.shields.io/coveralls/inveniosoftware/invenio-vocabularies.svg + :target: https://coveralls.io/r/inveniosoftware/invenio-vocabularies + +.. image:: https://img.shields.io/github/tag/inveniosoftware/invenio-vocabularies.svg + :target: https://github.com/inveniosoftware/invenio-vocabularies/releases + +.. image:: https://img.shields.io/pypi/dm/invenio-vocabularies.svg + :target: https://pypi.python.org/pypi/invenio-vocabularies + +.. image:: https://img.shields.io/github/license/inveniosoftware/invenio-vocabularies.svg + :target: https://github.com/inveniosoftware/invenio-vocabularies/blob/master/LICENSE + +Invenio module for managing vocabularies. + +TODO: Please provide feature overview of module + +Further documentation is available on +https://invenio-vocabularies.readthedocs.io/ diff --git a/babel.ini b/babel.ini new file mode 100644 index 00000000..1094c6ef --- /dev/null +++ b/babel.ini @@ -0,0 +1,24 @@ +# -*- coding: utf-8 -*- +# +# Copyright (C) 2020 CERN. +# +# Invenio-Vocabularies is free software; you can redistribute it and/or +# modify it under the terms of the MIT License; see LICENSE file for more +# details. + +# Extraction from Python source files + +[python: **.py] +encoding = utf-8 + +# Extraction from Jinja2 templates + +[jinja2: **/templates/**.html] +encoding = utf-8 +extensions = jinja2.ext.autoescape, jinja2.ext.with_ + +# Extraction from JavaScript files + +[javascript: **.js] +encoding = utf-8 +extract_messages = $._, jQuery._ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..8274a294 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,192 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " applehelp to make an Apple Help Book" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " coverage to run coverage check of the documentation (if enabled)" + +clean: + rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Invenio-Vocabularies.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Invenio-Vocabularies.qhc" + +applehelp: + $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp + @echo + @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." + @echo "N.B. You won't be able to view it unless you put it in" \ + "~/Library/Documentation/Help or install it in your application" \ + "bundle." + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/Invenio-Vocabularies" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Invenio-Vocabularies" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +coverage: + $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage + @echo "Testing of coverage in the sources finished, look at the " \ + "results in $(BUILDDIR)/coverage/python.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 00000000..7bbf7aec --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,19 @@ +.. + Copyright (C) 2020 CERN. + + Invenio-Vocabularies is free software; you can redistribute it and/or + modify it under the terms of the MIT License; see LICENSE file for more + details. + + +API Docs +======== + +.. automodule:: invenio_vocabularies.ext + :members: + +Views +----- + +.. automodule:: invenio_vocabularies.views + :members: diff --git a/docs/authors.rst b/docs/authors.rst new file mode 100644 index 00000000..10cf0ec4 --- /dev/null +++ b/docs/authors.rst @@ -0,0 +1,9 @@ +.. + Copyright (C) 2020 CERN. + + Invenio-Vocabularies is free software; you can redistribute it and/or + modify it under the terms of the MIT License; see LICENSE file for more + details. + + +.. include:: ../AUTHORS.rst diff --git a/docs/changes.rst b/docs/changes.rst new file mode 100644 index 00000000..d54d52d1 --- /dev/null +++ b/docs/changes.rst @@ -0,0 +1,9 @@ +.. + Copyright (C) 2020 CERN. + + Invenio-Vocabularies is free software; you can redistribute it and/or + modify it under the terms of the MIT License; see LICENSE file for more + details. + + +.. include:: ../CHANGES.rst diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..567d4a1a --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,324 @@ +# -*- coding: utf-8 -*- +# +# Copyright (C) 2020 CERN. +# +# Invenio-Vocabularies is free software; you can redistribute it and/or +# modify it under the terms of the MIT License; see LICENSE file for more +# details. + +"""Sphinx configuration.""" + +import os + +import sphinx.environment + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Do not warn on external images. +suppress_warnings = ['image.nonlocal_uri'] + +# 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.coverage', + 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', + '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 encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Invenio-Vocabularies' +copyright = u'2020, CERN' +author = u'CERN' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. + +# Get the version string. Cannot be done with import! +g = {} +with open(os.path.join(os.path.dirname(__file__), '..', + 'invenio_vocabularies', 'version.py'), + 'rt') as fp: + exec(fp.read(), g) + version = g['__version__'] + +# The full version, including alpha/beta/rc tags. +release = version + +# 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 + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- +html_theme = 'alabaster' + +html_theme_options = { + 'description': 'Invenio module for managing vocabularies.', + 'github_user': 'inveniosoftware', + 'github_repo': 'invenio-vocabularies', + 'github_button': False, + 'github_banner': True, + 'show_powered_by': False, + 'extra_nav_links': { + 'invenio-vocabularies@GitHub': 'https://github.com/inveniosoftware/invenio-vocabularies', + 'invenio-vocabularies@PyPI': 'https://pypi.python.org/pypi/invenio-vocabularies/', + } +} + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. + +# 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 = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# 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'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +html_sidebars = { + '**': [ + 'about.html', + 'navigation.html', + 'relations.html', + 'searchbox.html', + 'donate.html', + ] +} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' +#html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# Now only 'ja' uses this config value +#html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +#html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'invenio-vocabularies_namedoc' + +# -- 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, 'invenio-vocabularies.tex', u'invenio-vocabularies Documentation', + u'CERN', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- 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, 'invenio-vocabularies', u'invenio-vocabularies Documentation', + [author], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- 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, 'invenio-vocabularies', u'Invenio-Vocabularies Documentation', + author, 'invenio-vocabularies', 'Invenio module for managing vocabularies.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = { + 'python': ('https://docs.python.org/', None), + # TODO: Configure external documentation references, eg: + # 'Flask-Admin': ('https://flask-admin.readthedocs.io/en/latest/', None), +} + +# Autodoc configuraton. +autoclass_content = 'both' diff --git a/docs/configuration.rst b/docs/configuration.rst new file mode 100644 index 00000000..56649f78 --- /dev/null +++ b/docs/configuration.rst @@ -0,0 +1,13 @@ +.. + Copyright (C) 2020 CERN. + + Invenio-Vocabularies is free software; you can redistribute it and/or + modify it under the terms of the MIT License; see LICENSE file for more + details. + + +Configuration +============= + +.. automodule:: invenio_vocabularies.config + :members: diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 00000000..18f01865 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,9 @@ +.. + Copyright (C) 2020 CERN. + + Invenio-Vocabularies is free software; you can redistribute it and/or + modify it under the terms of the MIT License; see LICENSE file for more + details. + + +.. include:: ../CONTRIBUTING.rst diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..2dcf4038 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,47 @@ +.. + Copyright (C) 2020 CERN. + + Invenio-Vocabularies is free software; you can redistribute it and/or + modify it under the terms of the MIT License; see LICENSE file for more + details. + + +.. include:: ../README.rst + +User's Guide +------------ + +This part of the documentation will show you how to get started in using +Invenio-Vocabularies. + +.. toctree:: + :maxdepth: 2 + + installation + configuration + usage + +API Reference +------------- + +If you are looking for information on a specific function, class or method, +this part of the documentation is for you. + +.. toctree:: + :maxdepth: 2 + + api + +Additional Notes +---------------- + +Notes on how to contribute, legal information and changes are here for the +interested. + +.. toctree:: + :maxdepth: 1 + + contributing + changes + license + authors diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 00000000..12642fe6 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,9 @@ +.. + Copyright (C) 2020 CERN. + + Invenio-Vocabularies is free software; you can redistribute it and/or + modify it under the terms of the MIT License; see LICENSE file for more + details. + + +.. include:: ../INSTALL.rst diff --git a/docs/license.rst b/docs/license.rst new file mode 100644 index 00000000..a17c4d4f --- /dev/null +++ b/docs/license.rst @@ -0,0 +1,10 @@ +License +======= + +.. include:: ../LICENSE + +.. note:: + In applying this license, CERN does not waive the privileges and immunities + granted to it by virtue of its status as an Intergovernmental Organization or + submit itself to any jurisdiction. + diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..fca5c3ea --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,263 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=_build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +set I18NSPHINXOPTS=%SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over all changed/added/deprecated items + echo. xml to make Docutils-native XML files + echo. pseudoxml to make pseudoxml-XML files for display purposes + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + echo. coverage to run coverage check of the documentation if enabled + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + + +REM Check if sphinx-build is available and fallback to Python version if any +%SPHINXBUILD% 2> nul +if errorlevel 9009 goto sphinx_python +goto sphinx_ok + +:sphinx_python + +set SPHINXBUILD=python -m sphinx.__init__ +%SPHINXBUILD% 2> nul +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +:sphinx_ok + + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Invenio-Vocabularies.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Invenio-Vocabularies.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdf" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf + cd %~dp0 + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdfja" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf-ja + cd %~dp0 + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +if "%1" == "coverage" ( + %SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage + if errorlevel 1 exit /b 1 + echo. + echo.Testing of coverage in the sources finished, look at the ^ +results in %BUILDDIR%/coverage/python.txt. + goto end +) + +if "%1" == "xml" ( + %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The XML files are in %BUILDDIR%/xml. + goto end +) + +if "%1" == "pseudoxml" ( + %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. + goto end +) + +:end diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..c0377911 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +-e .[docs,tests] diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 00000000..d83fbdfa --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,12 @@ +.. + Copyright (C) 2020 CERN. + + Invenio-Vocabularies is free software; you can redistribute it and/or + modify it under the terms of the MIT License; see LICENSE file for more + details. + + +Usage +===== + +.. automodule:: invenio_vocabularies diff --git a/invenio_vocabularies/__init__.py b/invenio_vocabularies/__init__.py new file mode 100644 index 00000000..57586252 --- /dev/null +++ b/invenio_vocabularies/__init__.py @@ -0,0 +1,14 @@ +# -*- coding: utf-8 -*- +# +# Copyright (C) 2020 CERN. +# +# Invenio-Vocabularies is free software; you can redistribute it and/or +# modify it under the terms of the MIT License; see LICENSE file for more +# details. + +"""Invenio module for managing vocabularies.""" + +from .ext import InvenioVocabularies +from .version import __version__ + +__all__ = ('__version__', 'InvenioVocabularies') diff --git a/invenio_vocabularies/config.py b/invenio_vocabularies/config.py new file mode 100644 index 00000000..fbff8cb5 --- /dev/null +++ b/invenio_vocabularies/config.py @@ -0,0 +1,18 @@ +# -*- coding: utf-8 -*- +# +# Copyright (C) 2020 CERN. +# +# Invenio-Vocabularies is free software; you can redistribute it and/or +# modify it under the terms of the MIT License; see LICENSE file for more +# details. + +"""Invenio module for managing vocabularies.""" + +# TODO: This is an example file. Remove it if your package does not use any +# extra configuration variables. + +VOCABULARIES_DEFAULT_VALUE = 'foobar' +"""Default value for the application.""" + +VOCABULARIES_BASE_TEMPLATE = 'invenio_vocabularies/base.html' +"""Default base template for the demo page.""" diff --git a/invenio_vocabularies/ext.py b/invenio_vocabularies/ext.py new file mode 100644 index 00000000..d4b840d4 --- /dev/null +++ b/invenio_vocabularies/ext.py @@ -0,0 +1,43 @@ +# -*- coding: utf-8 -*- +# +# Copyright (C) 2020 CERN. +# +# Invenio-Vocabularies is free software; you can redistribute it and/or +# modify it under the terms of the MIT License; see LICENSE file for more +# details. + +"""Invenio module for managing vocabularies.""" + +from flask_babelex import gettext as _ + +from . import config + + +class InvenioVocabularies(object): + """Invenio-Vocabularies extension.""" + + def __init__(self, app=None): + """Extension initialization.""" + # TODO: This is an example of translation string with comment. Please + # remove it. + # NOTE: This is a note to a translator. + _('A translation string') + if app: + self.init_app(app) + + def init_app(self, app): + """Flask application initialization.""" + self.init_config(app) + app.extensions['invenio-vocabularies'] = self + + def init_config(self, app): + """Initialize configuration.""" + # Use theme's base template if theme is installed + if 'BASE_TEMPLATE' in app.config: + app.config.setdefault( + 'VOCABULARIES_BASE_TEMPLATE', + app.config['BASE_TEMPLATE'], + ) + for k in dir(config): + if k.startswith('VOCABULARIES_'): + app.config.setdefault(k, getattr(config, k)) diff --git a/invenio_vocabularies/templates/invenio_vocabularies/base.html b/invenio_vocabularies/templates/invenio_vocabularies/base.html new file mode 100644 index 00000000..ac24bd1b --- /dev/null +++ b/invenio_vocabularies/templates/invenio_vocabularies/base.html @@ -0,0 +1,16 @@ +{# + Copyright (C) 2020 CERN. + + Invenio-Vocabularies is free software; you can redistribute it and/or + modify it under the terms of the MIT License; see LICENSE file for more + details. +#} + + + + + + + {%- block page_body %}{%- endblock page_body %} + + diff --git a/invenio_vocabularies/templates/invenio_vocabularies/index.html b/invenio_vocabularies/templates/invenio_vocabularies/index.html new file mode 100644 index 00000000..dfe91919 --- /dev/null +++ b/invenio_vocabularies/templates/invenio_vocabularies/index.html @@ -0,0 +1,15 @@ +{# + Copyright (C) 2020 CERN. + + Invenio-Vocabularies is free software; you can redistribute it and/or + modify it under the terms of the MIT License; see LICENSE file for more + details. +#} + +{%- extends config.VOCABULARIES_BASE_TEMPLATE %} + +{%- block page_body %} +TODO: Example template, please remove if you do not need it. +{{_('Welcome to %(module_name)s', module_name=module_name)}} +{%- endblock %} + diff --git a/invenio_vocabularies/version.py b/invenio_vocabularies/version.py new file mode 100644 index 00000000..cee8c465 --- /dev/null +++ b/invenio_vocabularies/version.py @@ -0,0 +1,15 @@ +# -*- coding: utf-8 -*- +# +# Copyright (C) 2020 CERN. +# +# Invenio-Vocabularies is free software; you can redistribute it and/or +# modify it under the terms of the MIT License; see LICENSE file for more +# details. + +"""Version information for Invenio-Vocabularies. + +This file is imported by ``invenio_vocabularies.__init__``, +and parsed by ``setup.py``. +""" + +__version__ = '1.0.0.dev20200000' diff --git a/invenio_vocabularies/views.py b/invenio_vocabularies/views.py new file mode 100644 index 00000000..82853609 --- /dev/null +++ b/invenio_vocabularies/views.py @@ -0,0 +1,30 @@ +# -*- coding: utf-8 -*- +# +# Copyright (C) 2020 CERN. +# +# Invenio-Vocabularies is free software; you can redistribute it and/or +# modify it under the terms of the MIT License; see LICENSE file for more +# details. + +"""Invenio module for managing vocabularies.""" + +# TODO: This is an example file. Remove it if you do not need it, including +# the templates and static folders as well as the test case. + +from flask import Blueprint, render_template +from flask_babelex import gettext as _ + +blueprint = Blueprint( + 'invenio_vocabularies', + __name__, + template_folder='templates', + static_folder='static', +) + + +@blueprint.route("/") +def index(): + """Render a basic view.""" + return render_template( + "invenio_vocabularies/index.html", + module_name=_('Invenio-Vocabularies')) diff --git a/pytest.ini b/pytest.ini new file mode 100644 index 00000000..3c5a1b35 --- /dev/null +++ b/pytest.ini @@ -0,0 +1,11 @@ +# -*- coding: utf-8 -*- +# +# Copyright (C) 2020 CERN. +# +# Invenio-Vocabularies is free software; you can redistribute it and/or +# modify it under the terms of the MIT License; see LICENSE file for more +# details. + +[pytest] +addopts = --isort --pydocstyle --pycodestyle --doctest-glob="*.rst" --doctest-modules --cov=invenio_vocabularies --cov-report=term-missing +testpaths = docs tests invenio_vocabularies diff --git a/requirements-devel.txt b/requirements-devel.txt new file mode 100644 index 00000000..95507c92 --- /dev/null +++ b/requirements-devel.txt @@ -0,0 +1,13 @@ +# -*- coding: utf-8 -*- +# +# Copyright (C) 2020 CERN. +# +# Invenio-Vocabularies is free software; you can redistribute it and/or +# modify it under the terms of the MIT License; see LICENSE file for more +# details. +# +# TODO: Add development versions of some important dependencies here to get a +# warning when there are breaking upstream changes, e.g.: +# +# -e git+git://github.com/mitsuhiko/werkzeug.git#egg=Werkzeug +# -e git+git://github.com/mitsuhiko/jinja2.git#egg=Jinja2 diff --git a/run-tests.sh b/run-tests.sh new file mode 100755 index 00000000..c2ff8cb4 --- /dev/null +++ b/run-tests.sh @@ -0,0 +1,21 @@ +#!/usr/bin/env sh +# -*- coding: utf-8 -*- +# +# Copyright (C) 2020 CERN. +# +# Invenio-Vocabularies is free software; you can redistribute it and/or +# modify it under the terms of the MIT License; see LICENSE file for more +# details. + + +# TODO: Pass the services required by your module to the +# docker-services-cli e.g. `docker-services-cli up es postgresql redis` +# remove docker-services-cli if you don't need any of the services. +docker-services-cli up && \ +python -m check_manifest --ignore ".travis-*" && \ +python -m sphinx.cmd.build -qnNW docs docs/_build/html && \ +python -m pytest +python -m sphinx.cmd.build -qnNW -b doctest docs docs/_build/doctest +tests_exit_code=$? +docker-services-cli down +exit "$tests_exit_code" diff --git a/setup.cfg b/setup.cfg new file mode 100644 index 00000000..c432e041 --- /dev/null +++ b/setup.cfg @@ -0,0 +1,40 @@ +# -*- coding: utf-8 -*- +# +# Copyright (C) 2020 CERN. +# +# Invenio-Vocabularies is free software; you can redistribute it and/or +# modify it under the terms of the MIT License; see LICENSE file for more +# details. + + +[build_sphinx] +source-dir = docs/ +build-dir = docs/_build +all_files = 1 + +[bdist_wheel] +universal = 1 + +[pydocstyle] +add_ignore = D401 + +[pycodestyle] +exclude = docs/conf.py + +[compile_catalog] +directory = invenio_vocabularies/translations/ + +[extract_messages] +copyright_holder = CERN +msgid_bugs_address = info@inveniosoftware.org +mapping-file = babel.ini +output-file = invenio_vocabularies/translations/messages.pot +add-comments = NOTE + +[init_catalog] +input-file = invenio_vocabularies/translations/messages.pot +output-dir = invenio_vocabularies/translations/ + +[update_catalog] +input-file = invenio_vocabularies/translations/messages.pot +output-dir = invenio_vocabularies/translations/ diff --git a/setup.py b/setup.py new file mode 100644 index 00000000..bc02195d --- /dev/null +++ b/setup.py @@ -0,0 +1,104 @@ +# -*- coding: utf-8 -*- +# +# Copyright (C) 2020 CERN. +# +# Invenio-Vocabularies is free software; you can redistribute it and/or +# modify it under the terms of the MIT License; see LICENSE file for more +# details. + +"""Invenio module for managing vocabularies.""" + +import os + +from setuptools import find_packages, setup + +readme = open('README.rst').read() +history = open('CHANGES.rst').read() + +tests_require = [ + 'pytest-invenio>=1.4.0', +] + +extras_require = { + 'docs': [ + 'Sphinx>=3', + ], + 'tests': tests_require, +} + +extras_require['all'] = [] +for reqs in extras_require.values(): + extras_require['all'].extend(reqs) + +setup_requires = [ + 'Babel>=2.8', +] + +install_requires = [ + 'invenio-i18n>=1.2.0', +] + +packages = find_packages() + + +# Get the version string. Cannot be done with import! +g = {} +with open(os.path.join('invenio_vocabularies', 'version.py'), 'rt') as fp: + exec(fp.read(), g) + version = g['__version__'] + +setup( + name='invenio-vocabularies', + version=version, + description=__doc__, + long_description=readme + '\n\n' + history, + keywords='invenio TODO', + license='MIT', + author='CERN', + author_email='info@inveniosoftware.org', + url='https://github.com/inveniosoftware/invenio-vocabularies', + packages=packages, + zip_safe=False, + include_package_data=True, + platforms='any', + entry_points={ + 'invenio_base.apps': [ + 'invenio_vocabularies = invenio_vocabularies:InvenioVocabularies', + ], + 'invenio_base.blueprints': [ + 'invenio_vocabularies = invenio_vocabularies.views:blueprint', + ], + 'invenio_i18n.translations': [ + 'messages = invenio_vocabularies', + ], + # TODO: Edit these entry points to fit your needs. + # 'invenio_access.actions': [], + # 'invenio_admin.actions': [], + # 'invenio_assets.bundles': [], + # 'invenio_base.api_apps': [], + # 'invenio_base.api_blueprints': [], + # 'invenio_base.blueprints': [], + # 'invenio_celery.tasks': [], + # 'invenio_db.models': [], + # 'invenio_pidstore.minters': [], + # 'invenio_records.jsonresolver': [], + }, + extras_require=extras_require, + install_requires=install_requires, + setup_requires=setup_requires, + tests_require=tests_require, + classifiers=[ + 'Environment :: Web Environment', + 'Intended Audience :: Developers', + 'License :: OSI Approved :: MIT License', + 'Operating System :: OS Independent', + 'Programming Language :: Python', + 'Topic :: Internet :: WWW/HTTP :: Dynamic Content', + 'Topic :: Software Development :: Libraries :: Python Modules', + 'Programming Language :: Python :: 3', + 'Programming Language :: Python :: 3.6', + 'Programming Language :: Python :: 3.7', + 'Programming Language :: Python :: 3.8', + 'Development Status :: 1 - Planning', + ], +) diff --git a/tests/conftest.py b/tests/conftest.py new file mode 100644 index 00000000..3eb270f2 --- /dev/null +++ b/tests/conftest.py @@ -0,0 +1,45 @@ +# -*- coding: utf-8 -*- +# +# Copyright (C) 2020 CERN. +# +# Invenio-Vocabularies is free software; you can redistribute it and/or +# modify it under the terms of the MIT License; see LICENSE file for more +# details. + +"""Pytest configuration. + +See https://pytest-invenio.readthedocs.io/ for documentation on which test +fixtures are available. +""" + +import shutil +import tempfile + +import pytest +from flask import Flask +from flask_babelex import Babel + +from invenio_vocabularies import InvenioVocabularies +from invenio_vocabularies.views import blueprint + + +@pytest.fixture(scope='module') +def celery_config(): + """Override pytest-invenio fixture. + + TODO: Remove this fixture if you add Celery support. + """ + return {} + + +@pytest.fixture(scope='module') +def create_app(instance_path): + """Application factory fixture.""" + def factory(**config): + app = Flask('testapp', instance_path=instance_path) + app.config.update(**config) + Babel(app) + InvenioVocabularies(app) + app.register_blueprint(blueprint) + return app + return factory diff --git a/tests/test_invenio_vocabularies.py b/tests/test_invenio_vocabularies.py new file mode 100644 index 00000000..e6369c4f --- /dev/null +++ b/tests/test_invenio_vocabularies.py @@ -0,0 +1,39 @@ +# -*- coding: utf-8 -*- +# +# Copyright (C) 2020 CERN. +# +# Invenio-Vocabularies is free software; you can redistribute it and/or +# modify it under the terms of the MIT License; see LICENSE file for more +# details. + +"""Module tests.""" + +from flask import Flask + +from invenio_vocabularies import InvenioVocabularies + + +def test_version(): + """Test version import.""" + from invenio_vocabularies import __version__ + assert __version__ + + +def test_init(): + """Test extension initialization.""" + app = Flask('testapp') + ext = InvenioVocabularies(app) + assert 'invenio-vocabularies' in app.extensions + + app = Flask('testapp') + ext = InvenioVocabularies() + assert 'invenio-vocabularies' not in app.extensions + ext.init_app(app) + assert 'invenio-vocabularies' in app.extensions + + +def test_view(base_client): + """Test view.""" + res = base_client.get("/") + assert res.status_code == 200 + assert 'Welcome to Invenio-Vocabularies' in str(res.data)