Skip to content

Commit

Permalink
commented out inconsistent code formatting in parameter lists in docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@falexwolf
falexwolf committed Dec 9, 2018
1 parent a578ced commit 002b42b
Showing 1 changed file with 10 additions and 10 deletions.
20 changes: 10 additions & 10 deletions docs/_static/css/custom.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,17 +16,17 @@
font-size: 100%;
}

.rst-content dl:not(.docutils) dl dt code {
font-size: 100%;
font-weight: normal;
background: none transparent;
border: none;
padding: 0 2px;
}
/* .rst-content dl:not(.docutils) dl dt code { */
/* font-size: 100%; */
/* font-weight: normal; */
/* background: none transparent; */
/* border: none; */
/* padding: 0 2px; */
/* } */

.rst-content dl:not(.docutils) dl dt a.reference>code {
text-decoration: underline;
}
/* .rst-content dl:not(.docutils) dl dt a.reference>code { */
/* text-decoration: underline; */
/* } */

/* No narrow parameter lists for plot functions with images */
.rst-content .docutils.field-list {
Expand Down

7 comments on commit 002b42b

@falexwolf
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @flying-sheep; I have no idea why you changed the formatting of the code in the parameter lists, but the fact that the font sizes where inconsistent within the parameter lists themselves and the fact that the code formatting was inconsistent across usage of :class:'~anndata.AnnData', in non-parameter lists, e.g. here, and parameter lists, has bothered me for a couple of months now. 😉 Now, almost everything looks consistent and pretty again, in my opinion. The only leftover since the move from numpydoc to napoleon (with the automated generated parameter type introduction) that has not yet been fixed is the Return section of the docstrings; most of them need to be rewritten... While numpydoc was OK with return section that doesn't start with a type annotation, napoleon is not...

In any case, if there is no good reason to keep the css code, we can remove the commented out section. If there is a good reason, then let's please adapt it in a way that has a consistent appearance across the whole docs.

@flying-sheep
Copy link
Member

@flying-sheep flying-sheep commented on 002b42b Dec 9, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The reason it was there is that you wanted this. You said that generic types look ugly in the docs when I first wanted type annotation. And I agreed:

grafik

looks much better than

grafik

So I spent some time fiddling with the CSS until it looked pleasing.

@falexwolf
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, OK, so this was a misunderstanding - I guess I was referring to the bloated type strings produced by the type annotations, not about a specific font formatting.

I agree that the second line above doesn't look pretty. But the first line is inconsistent with the whole rest of the docs, both as it uses underlines, a different font size and no boxes.

I'll fiddle around a bit myself... ;)

@flying-sheep
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nono you definitely meant that. I showed you how it looked after the change and you were happy with the new look.

@falexwolf
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you remember that so clearly, you are probably right 😄 I'm starting to have a dejavu of the alternating sequence of boxes and brackets, too. In this case I simply missed that it would introduce further inconsistencies to solve it by changing fontsize and adding underlinings... I'll look into it...

@flying-sheep
Copy link
Member

@flying-sheep flying-sheep commented on 002b42b Dec 10, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sure! unrelatedly, why touch all the lines when adding /* before the block and */ after would have been sufficient?

you should train emacs to do that instead of block-commenting every line individually.

@falexwolf
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes, you're of course right; I'm just not editing css so often that it is worth training emacs for it :)

Please sign in to comment.