From f04d752bef0a2a46b07723487953f29d3930a59d Mon Sep 17 00:00:00 2001 From: Michael Hanke Date: Fri, 11 Feb 2022 07:50:03 +0100 Subject: [PATCH] Squashed commit of the following: MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit commit 0d19eeda18bb83be26564d08af6f91adc9268ad2 Merge: bfeaa45 84d672a Author: Michael Hanke Date: Thu Feb 10 15:29:49 2022 +0100 Merge pull request #32 from datalad/docs-explainer Add documentation explainer commit bfeaa45c1f269210897b91b2cb0ff690867c60a6 Merge: 1929a22 8e9bcbc Author: Michael Hanke Date: Thu Feb 10 15:27:24 2022 +0100 Merge pull request #30 from datalad/mslw-patch-1 Replace _metalad with _helloworld for easier grepping commit 84d672accb103b1a2396181565bb2e2ab6e5d38a Author: Stephan Heunis Date: Thu Feb 10 15:08:57 2022 +0100 add documentation explainer commit 8e9bcbc4b2a64e8bcd48059ed85c5c34321f5dad Author: Michał Szczepanik Date: Wed Feb 9 16:23:38 2022 +0100 Replace _metalad with _helloworld for easier grepping commit 1929a229214945e462f40cdcee6a339dfecc7124 Merge: ec54055 7b77859 Author: Michael Hanke Date: Mon Jan 24 10:29:45 2022 +0100 Merge pull request #29 from datalad/rf-tst Round of fixes and updates commit 7b77859c361ca2ff2ae7183069160fd5b8a329ff Author: Michael Hanke Date: Mon Jan 24 10:12:46 2022 +0100 Minimal codeclimate config commit 37b060672423ec4558c131d966c595b6638787e3 Author: Michael Hanke Date: Mon Jan 24 10:10:59 2022 +0100 More applicable command template With the command being in a dedicated file. Now also include standard logger naming suggestions. Fixes datalad/datalad-extension-template#27 commit 4aa498d49a315a5864393a5373fa64bc026a713a Author: Michael Hanke Date: Mon Jan 24 09:52:49 2022 +0100 Document what needs to be done for installing a git-annex snapshot Fixed datalad/datalad-extension-template#22 commit 7aea7b2c69d778433ffc60db22d5f9075e90fdbf Author: Michael Hanke Date: Mon Jan 24 09:50:18 2022 +0100 Update codecov setup to match datalad-core Fixes datalad/datalad-extension-template#24 commit ec5405566fd756d281f9d1fb73e25243a3d266e4 Merge: f6ef763 a3b022c Author: Michael Hanke Date: Tue Jan 11 17:22:44 2022 +0100 Merge pull request #28 from datalad/bf-version Make version detection robust to GIT_DIR specification commit a3b022cdf62e7637f46fc76b4e02ad2b4fb0735b Author: Chris Markiewicz Date: Tue Jan 11 10:37:27 2022 +0100 Make version detection robust to GIT_DIR specification Analog fix to https://github.com/datalad/datalad/pull/6341 commit f6ef763f94cefa953ef5dc1b037b06155a411933 Merge: b04f268 48addfb Author: Michael Hanke Date: Tue Jan 11 10:35:22 2022 +0100 Merge pull request #26 from datalad/no-setup-requires Stop using `setup_requires` commit b04f2685fea8d9e72cb4f03801b22986e7eecf5e Merge: cb64d9b 99a960f Author: Yaroslav Halchenko Date: Mon Oct 25 11:15:25 2021 -0400 Merge pull request #25 from datalad/no-distutils Stop using distutils commit 48addfbabc1ab65406f76324a329449948cad8b6 Author: John T. Wodder II Date: Mon Oct 25 09:20:18 2021 -0400 Stop using `setup_requires` commit 99a960ff3fa47a2b54412a8fb6c50ca48b447f06 Author: John T. Wodder II Date: Mon Oct 25 08:49:30 2021 -0400 Stop using distutils in _datalad_buildsupport commit c294de886d5de7d7597d97e93ff64dd8ed2909c2 Author: John T. Wodder II Date: Mon Oct 25 08:48:42 2021 -0400 Keep versioneer.py from using distutils --- _datalad_buildsupport/setup.py | 3 +-- docs/Makefile | 8 ++++---- docs/README.md | 35 ++++++++++++++++++++++++++++++++++ docs/source/conf.py | 2 +- setup.py | 9 --------- versioneer.py | 2 +- 6 files changed, 42 insertions(+), 17 deletions(-) create mode 100644 docs/README.md diff --git a/_datalad_buildsupport/setup.py b/_datalad_buildsupport/setup.py index 7f65a83..a4b92ed 100644 --- a/_datalad_buildsupport/setup.py +++ b/_datalad_buildsupport/setup.py @@ -9,12 +9,11 @@ import datetime import os -from distutils.core import Command -from distutils.errors import DistutilsOptionError from os.path import ( dirname, join as opj, ) +from setuptools import Command, DistutilsOptionError from setuptools.config import read_configuration import versioneer diff --git a/docs/Makefile b/docs/Makefile index dbfb529..048b48e 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -87,9 +87,9 @@ qthelp: @echo @echo "Build finished; now you can run "qcollectiongenerator" with the" \ ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/datalad_metalad.qhcp" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/datalad_mihextras.qhcp" @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/datalad_metalad.qhc" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/datalad_mihextras.qhc" applehelp: $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp @@ -104,8 +104,8 @@ devhelp: @echo @echo "Build finished." @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/datalad_metalad" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/datalad_metalad" + @echo "# mkdir -p $$HOME/.local/share/devhelp/datalad_mihextras" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/datalad_mihextras" @echo "# devhelp" epub: diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..d9d5ac4 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,35 @@ +## Editing, building, and publishing extension documentation + + +The `datalad-extension-template` uses [Sphinx](https://www.sphinx-doc.org/en/master/index.html#) for document generation +and suggests using [Read the Docs](https://docs.readthedocs.io/en/stable/) for automatic documentation building, versioning, and hosting. + +Once you are ready to document your extension software, take note of the following: + +### Document editing + +Edit your `docs/source/index.rst` file using [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html), +which is the default plaintext markup language used by Sphinx. Add further documentation as needed. + +### Local testing + +For testing locally whether your documentation builds and renders correctly, first install the developer requirements from the repository's root directory: +``` +pip install -r requirements-devel.txt +``` + +Then build the documentation locally: +``` +make -C docs html +``` + +Navigate to `docs/build/` and open `index.html` in your browser to view your documentation. + +### Remote building and testing + +The GitHub Action workflow located at `.github/workflows/docbuild.yml` will run on a push or pull request to your GitHub repository's master/main branch. This builds the documentation remotely and serves as an automated documentation test. + +### Publishing your documentation + +- If you maintain your extension yourself *outside of the scope of the DataLad GitHub organization*, you can follow [these instructions](https://docs.readthedocs.io/en/stable/integrations.html) for integrating your version control system (such as GitHub) with Read the Docs. +- If your extension is *maintained by the DataLad developer team*, please create an issue asking for help with the setup. diff --git a/docs/source/conf.py b/docs/source/conf.py index cf00aa1..cfbaf33 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,6 +1,6 @@ # -*- coding: utf-8 -*- # -# datalad_metalad documentation build configuration file, created by +# datalad_mihextras documentation build configuration file, created by # sphinx-quickstart on Tue Oct 13 08:41:19 2015. # # This file is execfile()d with the current directory set to its diff --git a/setup.py b/setup.py index 77b058f..6b4d1e0 100755 --- a/setup.py +++ b/setup.py @@ -11,17 +11,8 @@ cmdclass = versioneer.get_cmdclass() cmdclass.update(build_manpage=BuildManPage) -# Give setuptools a hint to complain if it's too old a version -# 43.0.0 allows us to put most metadata in setup.cfg and causes pyproject.toml -# to be automatically included in sdists -# Should match pyproject.toml -SETUP_REQUIRES = ['setuptools >= 43.0.0'] -# This enables setuptools to install wheel on-the-fly -SETUP_REQUIRES += ['wheel'] if 'bdist_wheel' in sys.argv else [] - if __name__ == '__main__': setup(name='datalad_mihextras', version=versioneer.get_version(), cmdclass=cmdclass, - setup_requires=SETUP_REQUIRES, ) diff --git a/versioneer.py b/versioneer.py index 64fea1c..51ca818 100644 --- a/versioneer.py +++ b/versioneer.py @@ -1500,7 +1500,7 @@ def get_cmdclass(): cmds = {} # we add "version" to both distutils and setuptools - from distutils.core import Command + from setuptools import Command class cmd_version(Command): description = "report generated version string"