ENH: adding sphinx documentation for the dandi-cli #712

yarikoptic · 2021-07-15T14:01:06Z

No description provided.

conf.py got tuned up by black after (git)lena:~/proj/dandi/dandi-cli-master[enh-sphinx]docs $> sphinx-quickstart Welcome to the Sphinx 3.4.3 quickstart utility. Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets). Selected root path: . You have two options for placing the build directory for Sphinx output. Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path. > Separate source and build directories (y/n) [n]: y The project name will occur in several places in the built documentation. > Project name: DANDI Archive CLI and Python API library > Author name(s): DANDI Team > Project release []: TODOdandi.__version__ If the documents are to be written in a language other than English, you can select a language here by its language code. Sphinx will then translate text that it generates into that language. For a list of supported codes, see https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language. > Project language [en]: Creating file /home/yoh/proj/dandi/dandi-cli-master/docs/source/conf.py. Creating file /home/yoh/proj/dandi/dandi-cli-master/docs/source/index.rst. Creating file /home/yoh/proj/dandi/dandi-cli-master/docs/Makefile. Creating file /home/yoh/proj/dandi/dandi-cli-master/docs/make.bat. Finished: An initial directory structure has been created. You should now populate your master file /home/yoh/proj/dandi/dandi-cli-master/docs/source/index.rst and create other documentation source files. Use the Makefile to build the docs, like so: make builder where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

codecov · 2021-07-15T14:03:52Z

Codecov Report

Merging #712 (7b6a862) into master (6b3f2a6) will decrease coverage by 0.03%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master     #712      +/-   ##
==========================================
- Coverage   84.06%   84.02%   -0.04%     
==========================================
  Files          59       59              
  Lines        5659     5659              
==========================================
- Hits         4757     4755       -2     
- Misses        902      904       +2

Flag	Coverage Δ
unittests	`84.02% <ø> (-0.04%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
dandi/dandiapi.py	`90.37% <ø> (-0.54%)`	⬇️
dandi/dandiarchive.py	`84.48% <ø> (ø)`
dandi/tests/skip.py	`88.88% <ø> (ø)`

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 6b3f2a6...7b6a862. Read the comment docs.

jwodder · 2021-07-15T14:35:34Z

@yarikoptic Just how much should be done for this PR? Is it OK if largely-placeholder pages are created for each page-worthy item, or should absolutely everything be documented? Something in between?

yarikoptic · 2021-07-15T17:10:44Z

@yarikoptic Just how much should be done for this PR? Is it OK if largely-placeholder pages are created for each page-worthy item, or should absolutely everything be documented? Something in between?

I think something in between -- just concentrated on what would be relevant to the user, so they could get a good idea of interfaces they could/should use and what they provide. For the use-cases and example I guess we would just do them in the handbook, and should link to it from this documentation.

yarikoptic · 2021-07-15T17:12:18Z

docs/source/cmdline/delete.rst

+Options
+-------
+
+.. option:: --skip-missing


oh -- you just manually produced them? great for now but we should look into making them generated automagically... may be smth like https://github.com/click-contrib/sphinx-click could be used ?

I don't really like the way the sphinx-click output looks.

May be there is a way to improve that? I just fear that manually produced docs would quickly become our of sync with actual CLI

yarikoptic · 2021-07-16T16:46:08Z

tox.ini

+basepython = python3
+deps = -rdocs/requirements.txt
+changedir = docs
+commands = sphinx-build -E -b html source build


Suggested change

commands = sphinx-build -E -b html source build

commands = sphinx-build -E -W -b html source build

so warnings are treated as errors? (if so -- please also add to docs/Makefile SPHINXOPTS) . unfortunately it would then error out upon encountering the first one,

ATM I still observe some warnings to be dealt with

$> python3 `which sphinx-build` -E -W -b html source build Running Sphinx v3.4.3 building [mo]: targets for 0 po files that are out of date building [html]: targets for 16 source files that are out of date updating environment: [new config] 16 added, 0 changed, 0 removed reading sources... [100%] modref/utils Warning, treated as error: /home/yoh/proj/dandi/dandi-cli-master/docs/source/cmdline/organize.rst:41:Unknown directive type "options". .. options:: -d, --dandiset-path <dir> A top directory (local) of the dandiset to organize files under. If not specified, dandiset current directory is under is assumed. For 'simulate' mode target dandiset/directory must not exist. (dev3) 1 22202 ->2.....................................:Fri 16 Jul 2021 12:44:05 PM EDT:. (git)lena:~/proj/dandi/dandi-cli-master[enh-sphinx]docs $> python3 `which sphinx-build` -E -b html source build Running Sphinx v3.4.3 building [mo]: targets for 0 po files that are out of date building [html]: targets for 16 source files that are out of date updating environment: [new config] 16 added, 0 changed, 0 removed reading sources... [100%] modref/utils /home/yoh/proj/dandi/dandi-cli-master/docs/source/cmdline/organize.rst:41: WARNING: Unknown directive type "options". .. options:: -d, --dandiset-path <dir> A top directory (local) of the dandiset to organize files under. If not specified, dandiset current directory is under is assumed. For 'simulate' mode target dandiset/directory must not exist. /home/yoh/proj/dandi/dandi-cli-master/dandi/dandiapi.py:docstring of dandi.dandiapi.RemoteDandiset.iter_upload_raw_asset:6: WARNING: Unexpected section title. Parameters ---------- /home/yoh/proj/dandi/dandi-cli-master/dandi/dandiapi.py:docstring of dandi.dandiapi.RemoteDandiset.iter_upload_raw_asset:17: WARNING: Unexpected section title. Returns ------- /home/yoh/proj/dandi/dandi-cli-master/dandi/dandiapi.py:docstring of dandi.dandiapi.RemoteDandiset.upload_raw_asset:6: WARNING: Unexpected section title. Parameters ---------- /home/yoh/proj/dandi/dandi-cli-master/dandi/dandiarchive.py:docstring of dandi.dandiarchive.navigate_url:4: WARNING: Unexpected section title. Parameters ---------- /home/yoh/proj/dandi/dandi-cli-master/dandi/dandiarchive.py:docstring of dandi.dandiarchive.navigate_url:9: WARNING: Unexpected section title. Yields ------ /home/yoh/proj/dandi/dandi-cli-master/dandi/dandiarchive.py:docstring of dandi.dandiarchive._dandi_url_parser.parse:5: WARNING: Unexpected indentation. /home/yoh/proj/dandi/dandi-cli-master/dandi/dandiarchive.py:docstring of dandi.dandiarchive._dandi_url_parser.parse:16: WARNING: Inline interpreted text or phrase reference start-string without end-string. /home/yoh/proj/dandi/dandi-cli-master/dandi/dandiarchive.py:docstring of dandi.dandiarchive._dandi_url_parser.parse:20: WARNING: Unexpected section title. Returns ------- /home/yoh/proj/dandi/dandi-cli-master/docs/source/modref/index.rst.rst:44: WARNING: autosummary: stub file not found 'dandi.tests.fixtures'. Check your autosummary_generate setting. /home/yoh/proj/dandi/dandi-cli-master/docs/source/modref/index.rst.rst:44: WARNING: autosummary: stub file not found 'dandi.tests.skip'. Check your autosummary_generate setting. looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] modref/utils /home/yoh/proj/dandi/dandi-cli-master/docs/source/cmdline/upload.rst:10: WARNING: unknown option: --dandiset-path generating indices... genindex py-modindex done writing additional pages... search done copying static files... done copying extra files... done dumping search index in English (code: en)... done dumping object inventory... done build succeeded, 12 warnings. The HTML pages are in build.

Done & fixed.

yarikoptic · 2021-07-16T17:59:28Z

Great, thank you @jwodder

yarikoptic added 3 commits July 14, 2021 14:05

rename doc to docs for consistency with e.g. datalad

56333d7

initial bits and pieces

481b620

yarikoptic assigned jwodder Jul 15, 2021

Build with tox

02bf07f

jwodder force-pushed the enh-sphinx branch from 0ae7c68 to 02bf07f Compare July 15, 2021 14:13

Show more details for dandiapi and dandiarchive

5c1348c

yarikoptic mentioned this pull request Jul 15, 2021

Deploy sphinx-produced docs to RTD #713

Closed

3 tasks

jwodder marked this pull request as draft July 15, 2021 14:34

yarikoptic mentioned this pull request Jul 15, 2021

Add new API design doc #447

Merged

More docs pages

d8ae55e

yarikoptic commented Jul 15, 2021

View reviewed changes

Make --jobs arg consistent

b6224fb

jwodder marked this pull request as ready for review July 16, 2021 16:35

Add "Build Docs" workflow

385fbe8

jwodder force-pushed the enh-sphinx branch from dfc0dcb to 385fbe8 Compare July 16, 2021 16:43

yarikoptic commented Jul 16, 2021

View reviewed changes

jwodder added 2 commits July 16, 2021 12:46

Typo

6ef7fa9

Fix Sphinx warnings and convert new ones into errors

7b6a862

yarikoptic added the documentation Changes only affect the documentation label Jul 16, 2021

yarikoptic merged commit a33b3f9 into master Jul 16, 2021

yarikoptic deleted the enh-sphinx branch July 16, 2021 18:00

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ENH: adding sphinx documentation for the dandi-cli #712

ENH: adding sphinx documentation for the dandi-cli #712

yarikoptic commented Jul 15, 2021

codecov bot commented Jul 15, 2021 •

edited

Loading

jwodder commented Jul 15, 2021

yarikoptic commented Jul 15, 2021

yarikoptic Jul 15, 2021

jwodder Jul 16, 2021

yarikoptic Jul 16, 2021

yarikoptic Jul 16, 2021

jwodder Jul 16, 2021

yarikoptic commented Jul 16, 2021

	commands = sphinx-build -E -b html source build
	commands = sphinx-build -E -W -b html source build

ENH: adding sphinx documentation for the dandi-cli #712

ENH: adding sphinx documentation for the dandi-cli #712

Conversation

yarikoptic commented Jul 15, 2021

codecov bot commented Jul 15, 2021 • edited Loading

Codecov Report

jwodder commented Jul 15, 2021

yarikoptic commented Jul 15, 2021

yarikoptic Jul 15, 2021

Choose a reason for hiding this comment

jwodder Jul 16, 2021

Choose a reason for hiding this comment

yarikoptic Jul 16, 2021

Choose a reason for hiding this comment

yarikoptic Jul 16, 2021

Choose a reason for hiding this comment

jwodder Jul 16, 2021

Choose a reason for hiding this comment

yarikoptic commented Jul 16, 2021

codecov bot commented Jul 15, 2021 •

edited

Loading