astropy / astropy/pyvo

DOC: ensure examples in documentation are not skipped

Open
#704 0 comments 0 reactions 0 assignees View on GitHub
component: mivot documentation
Dominant language
Python
Stars
88
Forks
64
Avg merge
38m
Merged PRs (30d)
1

Description

Some of the MIVOT/MANGO documentation examples are skipped at the moment.

I would be preferable if we would test all the examples we include in the narrative docs to ensure what we show to end users actually keep working.

The only exceptions are the extremely resource intensive examples like running a query that is way too wide scoped, we have a few of those in the registry docs. For any such cases we should aim to provide a comment line in the docs source code so the reason for the skip is easy to see.

I'm labeling it as mivot, but there are a couple more cases in `docs/dal/index.rst`, too, and maybe there are still code snippets that are not in the doctest format and thus are always skipped.

Tasks:

- [ ] look for `doctest-skip` directives, endure each have a reason stated in a comment, remove the skip from as many as reasonably possible
- [ ] look for `code-block` directives, add `>>>` to them so they can be picked up by the testing infra

Contributor guide

No contributing guide indexed for this repository

Research direction

Search the documentation sources for `doctest-skip` and `code-block` directives, including `docs/dal/index.rst`, and inspect the MIVOT/MANGO examples first. Run the documentation doctest checks to identify examples that can be enabled. Done means reasonably runnable examples are tested, while resource-intensive skips retain an explanatory comment.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation, testing
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.