in docs, improve three-way linking between type and representations #1691
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Why can't I see these changes on the docs artifacts? |
|
Either sphinx cached incorrectly or it's not writing the added text: https://ci.hail.is/repository/download/HailSourceCode_HailMainline_BuildDocs/18456:id/www/hail/expr/hail.expr.TInt.html#hail.expr.TInt |
danking
changed the title
Discussion of issue: spatialaudio/nbsphinx#24 (comment) Root cause: ContinuumIO/anaconda-issues#1430
1. Remove reference to sample 2. Move ico to correct directory
This triggers an error message:
Error in "include" directive: no content permitted.
because the one-space-indented text is assumed to be an argument to the
`.. include` directive
Also fix location of hailType.rst
danking
force-pushed
the
improve-doc-links
branch
from
873376f
to
c581cf7
Compare
|
First merge: #1693 |
danking
changed the title
cseed
requested changes
Apr 20, 2017
|
|
||
| .. include:: hailType.rst | ||
|
|
||
| - `expression language documentation <types.html#int>`__ |
There was a problem hiding this comment.
I found the transition to the bulleted list confusing.
python/hail/docs/expr/hailType.rst
Outdated
| @@ -0,0 +1,11 @@ | |||
| This is the representation of and documentation for a Hail type. Values of this | |||
| type have two representations: the expression language representation and the | |||
| Python representation. This is confusing! There are two sets of documentation | |||
There was a problem hiding this comment.
Is it helpful to say "This is confusing!"?
python/hail/docs/expr/hailType.rst
Outdated
| type have two representations: the expression language representation and the | ||
| Python representation. This is confusing! There are two sets of documentation | ||
| for many objects like Variant and Genotype. In methods like | ||
| :py:meth:`~hail.VariantDataset.annotate_variants_expr` and |
There was a problem hiding this comment.
I think this is too much. You introduced the two kinds of values, then you went on to discuss various kinds of functions. I would just say there are two kinds of values, in expressions and in Python. Then link to the two kinds. Will also make the transition to the bulleted lists smoother.
python/hail/docs/expr/hailType.rst
Outdated
| @@ -0,0 +1,11 @@ | |||
| This is the representation of and documentation for a Hail type. Values of this | |||
|
@cseed back to you |
cseed
approved these changes
Apr 21, 2017
liameabbott
pushed a commit
to liameabbott/hail
that referenced
this pull request
May 3, 2017
…ail-is#1691) * eliminate warning in getting_started.rst * all warnings are errors * use anonymous links instead of named links * fix indentation of list item * fix a variety of list item syntax issues * remove illegal excess indentation * several list item syntax fixes * variety of list item fixes and a link fix * remove extraneous character from string [] docs * favicons must end in ico * work around a bug in conda Discussion of issue: spatialaudio/nbsphinx#24 (comment) Root cause: ContinuumIO/anaconda-issues#1430 * fix link to tutorial * fix broken links * remove broken link to sample * remove more broken links to sample * remove references to sec-objects * fix bad reference syntax * two small fixes 1. Remove reference to sample 2. Move ico to correct directory * remove unnecessary html_extra_path entry * initial attempt * add missing file * improve hailType blurb * further improvements from tpoterba * Update hailType.rst * sphinx lists must not have leading space This triggers an error message: Error in "include" directive: no content permitted. because the one-space-indented text is assumed to be an argument to the `.. include` directive Also fix location of hailType.rst * use anonymous links instead of named links * simplify docs
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.