Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

doc: colorize deprecated api notes #3898

Closed
wants to merge 1 commit into from

3 participants

@defunctzombie

API stability notes are very easy to overlook since they are the same
color as other code snippets. Likewise, deprecated and non deprecated
api look the same and give no visual feedback (other than a number
change) that one should not use the particular api. Using red for the
outline of deprecated api notes brings attention to the fact they are
deprecated.

@defunctzombie defunctzombie doc: colorize deprecated api notes
API stability notes are very easy to overlook since they are the same
color as other code snippets. Likewise, deprecated and non deprecated
api look the same and give no visual feedback (other than a number
change) that one should not use the particular api. Using red for the
outline of deprecated api notes brings attention to the fact they are
deprecated.
8ce87d3
@bnoordhuis

Can't this be solved at generation time?

@isaacs
Owner

Agree with @bnoordhuis's leading question.

I like the idea of colorizing these, and not just for deprecation, necessarily, either. But, it should just add the class in the tag when it generates it. Check out the tools/doc/ program for the bits that make the doc markup.

@defunctzombie

So the issue is that the html is generated all at once. The way it is done currently does not expose a way to just "insert a class" into the tag. One possible solution is to update the marked package to the version that calls a callback for highlighed areas (see readme https://github.com/chjj/marked). Then wrap the passed in code using a tag and class we control. And one other way would be to read the generated html file into jsdom (or similar) and do the above except at generation time versus render time.

@bnoordhuis

Updating the markdown parser sounds like the best option.

@luk- luk- referenced this pull request from a commit in luk-/node
@luk- luk- Colorize API stabilitity index headers in docs
Noted in @shtylman's #3898, API stability notes are easy to overlook
in the html documentation. This can be especially troublesome if the API
is deprecated. This commit gives visual feedback by adding in a class
to the html docs when they're generated. The API headers with
corresponding colors are also listed in the 'About this Documentation'
page for easy reference.
aa8e0e6
@luk- luk- referenced this pull request from a commit in luk-/node
@luk- luk- Colorize API stabilitity index headers in docs
Noted in @shtylman's #3898, API stability notes are easy to overlook
in the html documentation. This can be especially troublesome if the API
is deprecated. This commit gives visual feedback by adding in a class
to the html docs when they're generated. The API headers with
corresponding colors are also listed in the 'About this Documentation'
page for easy reference.
a9525fd
@isaacs isaacs referenced this pull request from a commit
@luk- luk- Colorize API stabilitity index headers in docs
Noted in @shtylman's #3898, API stability notes are easy to overlook
in the html documentation. This can be especially troublesome if the API
is deprecated. This commit gives visual feedback by adding in a class
to the html docs when they're generated. The API headers with
corresponding colors are also listed in the 'About this Documentation'
page for easy reference.
192192a
@defunctzombie defunctzombie deleted the branch
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Aug 21, 2012
  1. @defunctzombie

    doc: colorize deprecated api notes

    defunctzombie authored
    API stability notes are very easy to overlook since they are the same
    color as other code snippets. Likewise, deprecated and non deprecated
    api look the same and give no visual feedback (other than a number
    change) that one should not use the particular api. Using red for the
    outline of deprecated api notes brings attention to the fact they are
    deprecated.
This page is out of date. Refresh to see the latest.
View
1  Makefile
@@ -124,6 +124,7 @@ website_files = \
out/doc/index.html \
out/doc/v0.4_announcement.html \
out/doc/cla.html \
+ out/doc/doc.js \
out/doc/sh_main.js \
out/doc/sh_javascript.min.js \
out/doc/sh_vim-dark.css \
View
4 doc/api_assets/doc.css
@@ -0,0 +1,4 @@
+
+.api_stability_0 {
+ border-color: red;
+}
View
10 doc/doc.js
@@ -0,0 +1,10 @@
+
+var nodes = document.getElementsByTagName('pre');
+
+for (var i=0 ; i< nodes.length ; ++i) {
+ var element = nodes.item(i);
+ if (element.innerHTML.indexOf('Stability: 0') >= 0) {
+ element.className += 'api_stability_0';
+ }
+}
+
View
2  doc/template.html
@@ -5,6 +5,7 @@
<title>__SECTION__ Node.js __VERSION__ Manual &amp; Documentation</title>
<link rel="stylesheet" href="assets/style.css">
<link rel="stylesheet" href="assets/sh.css">
+ <link rel="stylesheet" href="assets/doc.css">
<link rel="canonical" href="http://nodejs.org/api/__FILENAME__.html">
</head>
<body class="alt apidoc" id="api-section-__FILENAME__">
@@ -69,6 +70,7 @@
<p>Copyright <a href="http://joyent.com/">Joyent, Inc</a>, Node.js is a <a href="/trademark-policy.pdf">trademark</a> of Joyent, Inc. View <a href="https://raw.github.com/joyent/node/__VERSION__/LICENSE">license</a>.</p>
</div>
+ <script src="../doc.js"></script>
<script src="../sh_main.js"></script>
<script src="../sh_javascript.min.js"></script>
<script>highlight(undefined, undefined, 'pre');</script>
Something went wrong with that request. Please try again.