diff --git a/.gitignore b/.gitignore index 1983db653d..82fa56577f 100644 --- a/.gitignore +++ b/.gitignore @@ -9,6 +9,7 @@ */*/.DS_Store */*/*/.DS_Store .metadata +.ipynb_checkpoints /venv*/ /.idea/ @@ -28,3 +29,7 @@ coverage.xml # Build files dist/ pip-wheel-metadata + +# Docs +docs/build +docs/source/apidoc diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index bcfa7bd174..d3e83f5dd8 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -133,19 +133,6 @@ repos: utils/dependency_management.py )$ - - id: rtd-requirements - name: Validate docs/requirements_for_rtd.txt - entry: python ./utils/dependency_management.py validate-rtd-reqs - language: system - pass_filenames: false - files: >- - (?x)^( - setup.json| - setup.py| - utils/dependency_management.py| - docs/requirements_for_rtd.txt| - )$ - - id: pyproject name: Validate pyproject.toml entry: python ./utils/dependency_management.py validate-pyproject-toml diff --git a/.readthedocs.yml b/.readthedocs.yml index 9e2f9cf76b..1bf9dbfc90 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -1,14 +1,22 @@ -# Configuration for readthedocs +version: 2 # Important: we need to disable all unneeded formats. -# Note that HTML and JSON are always built: -# https://docs.readthedocs.io/en/latest/yaml-config.html#formats -# Especially, the 'htmlzip' format takes a LOT of memory and causes -# the build to fail - see our issue #1472: +# Note that HTML and JSON are always built: https://docs.readthedocs.io/en/latest/yaml-config.html#formats +# Especially, the 'htmlzip' format takes a LOT of memory and causes the build to fail - see our issue #1472: # https://github.com/aiidateam/aiida-core/issues/1472 formats: [] -## For now I don't specify any other parameter, that is -## currently setup in the web page of Read the Docs. -## For other parameters see -## https://docs.readthedocs.io/en/latest/yaml-config.html +# Need to install the package itself such that the entry points are installed and the API doc can build properly +python: + version: 3.8 + install: + - method: pip + path: . + extra_requirements: + - docs + - tests + +# Let the build fail if there are any warnings +sphinx: + builder: html + fail_on_warning: true diff --git a/aiida/sphinxext/tests/.gitignore b/aiida/sphinxext/tests/.gitignore deleted file mode 100644 index 378eac25d3..0000000000 --- a/aiida/sphinxext/tests/.gitignore +++ /dev/null @@ -1 +0,0 @@ -build diff --git a/docs/.gitignore b/docs/.gitignore deleted file mode 100644 index 378eac25d3..0000000000 --- a/docs/.gitignore +++ /dev/null @@ -1 +0,0 @@ -build diff --git a/docs/README.rst b/docs/README.rst deleted file mode 100644 index 674dff08b2..0000000000 --- a/docs/README.rst +++ /dev/null @@ -1,20 +0,0 @@ -To build the documentation in sphinx, from this folder -run:: - - make html - -This generates a html documentation tree under docs/build/html - -You can browse to docs/build/html/index.html to see the documentation -in html format. - -.. note:: However, that this requires to have AiiDA already installed - on your computer (and sphinx installed, too). - - If you received a distribution file, you should already find - the compiled documentation in docs/build/html/index.html. - -.. note:: for a nicer html format, install the Read The Docs theme, - using:: - - sudo pip install sphinx_rtd_theme diff --git a/docs/requirements_for_rtd.txt b/docs/requirements_for_rtd.txt deleted file mode 100644 index 967786656f..0000000000 --- a/docs/requirements_for_rtd.txt +++ /dev/null @@ -1,60 +0,0 @@ -PyCifRW~=4.4 -aiida-export-migration-tests==0.9.0 -aldjemy~=0.9.1 -alembic~=1.2 -ase~=3.18 -circus~=0.16.1 -click-completion~=0.5.1 -click-config-file~=0.6.0 -click-spinner~=0.1.8 -click~=7.0 -coverage<5.0 -django~=2.2 -docutils==0.15.2 -ete3~=3.1 -flask-cors~=3.0 -flask-restful~=0.3.7 -flask~=1.1 -graphviz~=0.13 -ipython~=7.0 -jinja2~=2.10 -kiwipy[rmq]~=0.5.5 -numpy<1.18,~=1.17 -paramiko~=2.6 -pg8000~=1.13 -pgsu~=0.1.0 -pgtest>=1.3.1,~=1.3 -pika~=1.1 -plumpy~=0.15.0 -psutil~=5.6 -psycopg2-binary>=2.8.3,~=2.8 -pyblake2~=1.1; python_version < "3.6" -pydata-sphinx-theme~=0.3.0 -pygments~=2.5 -pymatgen>=2019.7.2 -pymysql~=0.9.3 -pyparsing~=2.4 -pytest-cov~=2.7 -pytest-timeout~=1.3 -pytest~=5.4 -python-dateutil~=2.8 -python-memcached~=1.59 -pytz~=2019.3 -pyyaml~=5.1.2 -reentry~=1.3 -seekpath>=1.9.3,~=1.9 -simplejson~=3.16 -spglib~=1.14 -sphinx-copybutton~=0.2.12 -sphinx-panels~=0.4.0 -sphinxcontrib-details-directive~=0.1.0 -sphinx~=2.2 -sqlalchemy-diff~=0.1.3 -sqlalchemy-utils~=0.34.2 -sqlalchemy>=1.3.10,~=1.3 -tabulate~=0.8.5 -tornado<5.0 -tqdm~=4.45 -tzlocal~=2.0 -upf_to_json~=0.9.2 -wrapt~=1.11.1 diff --git a/docs/source/.gitignore b/docs/source/.gitignore deleted file mode 100644 index ef6e0026f0..0000000000 --- a/docs/source/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -apidoc -.ipynb_checkpoints/ diff --git a/docs/source/conf.py b/docs/source/conf.py index 70f88a803f..850318791e 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -21,22 +21,13 @@ import os import sys -# Add `aiida` to the path so it can be imported without installing it -sys.path.append(os.path.join(os.path.split(__file__)[0], os.pardir, os.pardir)) - import aiida from aiida.manage.configuration import load_documentation_profile -# a reentry scan is required in RTD, to ensure all the API can be imported -import reentry -reentry.manager.scan() - # Load the dummy profile even if we are running locally, this way the documentation will succeed even if the current # default profile of the AiiDA installation does not use a Django backend. load_documentation_profile() -ON_RTD = os.environ.get('READTHEDOCS', None) - # 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. diff --git a/utils/dependency_management.py b/utils/dependency_management.py index 8c8c63dbf2..9a719ee2d5 100755 --- a/utils/dependency_management.py +++ b/utils/dependency_management.py @@ -118,18 +118,6 @@ def _parse_working_set(entries): yield _Entry(req) -def _generate_rtd_requirement_set(): - """Generate content of docs/requirements_for_rtd.txt file.""" - - # Read the requirements from 'setup.json' - setup_cfg = _load_setup_cfg() - install_requirements = {Requirement.parse(r) for r in setup_cfg['install_requires']} - for key in ('tests', 'docs', 'rest', 'atomic_tools'): - install_requirements.update({Requirement.parse(r) for r in setup_cfg['extras_require'][key]}) - - return install_requirements - - @click.group() def cli(): """Manage dependencies of the aiida-core package.""" @@ -172,15 +160,6 @@ def generate_environment_yml(): ) -@cli.command('generate-rtd-reqs') -def generate_requirements_for_rtd(): - """Generate 'docs/requirements_for_rtd.txt' file.""" - install_requirements = _generate_rtd_requirement_set() - - with open(ROOT / Path('docs', 'requirements_for_rtd.txt'), 'w') as handle: - handle.write('{}\n'.format('\n'.join(sorted(map(str, install_requirements))))) - - @cli.command() def generate_pyproject_toml(): """Generate 'pyproject.toml' file.""" @@ -211,7 +190,6 @@ def generate_pyproject_toml(): def generate_all(ctx): """Generate all dependent requirement files.""" ctx.invoke(generate_environment_yml) - ctx.invoke(generate_requirements_for_rtd) ctx.invoke(generate_pyproject_toml) @@ -287,23 +265,6 @@ def validate_environment_yml(): # pylint: disable=too-many-branches click.secho('Conda dependency specification is consistent.', fg='green') -@cli.command('validate-rtd-reqs', help="Validate 'docs/requirements_for_rtd.txt'.") -def validate_requirements_for_rtd(): - """Validate that 'docs/requirements_for_rtd.txt' is consistent with 'setup.json'.""" - - # Read the requirements from 'setup.json' - install_requirements = _generate_rtd_requirement_set() - - with open(ROOT / Path('docs', 'requirements_for_rtd.txt')) as reqs_file: - reqs = {Requirement.parse(r) for r in reqs_file} - - if reqs != install_requirements: - click.echo('{}'.format(reqs - install_requirements)) - raise DependencySpecificationError("The requirements for RTD are inconsistent with 'setup.json'.") - - click.secho('RTD requirements specification is consistent.', fg='green') - - @cli.command('validate-pyproject-toml', help="Validate 'pyproject.toml'.") def validate_pyproject_toml(): """Validate that 'pyproject.toml' is consistent with 'setup.json'.""" @@ -347,11 +308,9 @@ def validate_all(ctx): - setup.json - environment.yml - pyproject.toml - - docs/requirements_for_rtd.txt """ ctx.invoke(validate_environment_yml) - ctx.invoke(validate_requirements_for_rtd) ctx.invoke(validate_pyproject_toml)