Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

generate.js doc tool produces incomplete json #1545

Closed
gromnitsky opened this issue Apr 28, 2015 · 6 comments
Closed

generate.js doc tool produces incomplete json #1545

gromnitsky opened this issue Apr 28, 2015 · 6 comments
Labels
doc Issues and PRs related to the documentations. good first issue Issues that are suitable for first-time contributors.

Comments

@gromnitsky
Copy link
Contributor

The output from

$ node generate.js ../../doc/api/debugger.markdown

doesn't correspond to its markdown source. For example, ### Info section is missing, both ### Execution control & ### Various sections lack expected desc property.

@mscdex mscdex added the doc Issues and PRs related to the documentations. label Apr 28, 2015
@Fishrock123
Copy link
Contributor

cc @robertkowalski?

@Fishrock123
Copy link
Contributor

Honestly, I don't think anyone has really maintained the docs tool in years. long-term plan is to replace it with some other community maintained documentation generator.

There is also a separate repo for it, though again, no-one maintains it. https://github.com/iojs/doc-tool

@Trott Trott added the good first issue Issues that are suitable for first-time contributors. label Feb 24, 2016
@Trott
Copy link
Member

Trott commented Feb 24, 2016

If we just want to patch in a fix here, this might be a good first contribution for someone. Tagging it as such. Feel free to remove the label if we don't really want this to get fixed here but would rather it get fixed in the separate repo.

If someone does fix it, they might also want to update the marked module that the tool depends on.

@firedfox
Copy link
Contributor

firedfox commented Mar 2, 2016

This problem is caused by a bug processing unordered list which is directly following a heading.
Most of such lists are Commands reference, AFAICS.
In HTML result, an unordered list following a heading would be wrapped by a <div class="signature">, for instance:

### Various

* `scripts` - List all loaded scripts
* `version` - Display V8's version

would be converted to:

<h3>Various</h3>
<div class="signature">
  <ul>
    <li><code>scripts</code> - List all loaded scripts</li>
    <li><code>version</code> - Display V8&#39;s version</li>
  </ul>
</div>

Shall we also wrap the list in the JSON result? Such as:

{
  "textRaw": "Various",
  "name": "various",
  "desc": "<div class="signature"><ul><li><code>scripts</code> - List all loaded scripts</li>
<li><code>version</code> - Display V8&#39;s version</li></ul></div>",
  "type": "module",
  "displayName": "Various"
}

Or shall we just leave it alone without any wrapping?
Maybe I can make my first contribution once figure it out.

@Trott
Copy link
Member

Trott commented Mar 2, 2016

/cc @nodejs/documentation

@firedfox
Copy link
Contributor

Above PR added a default case to processList function. All missing lists are put into desc as uls without any extra wrapping. The json is complete now.
This is the diff result generated from all.markdown before and after the patch: http://106.187.89.52/tmp/diff-json.html

MylesBorins pushed a commit that referenced this issue Apr 11, 2016
Doc tool produces incomplete json when it meets unordered lists that
directly following a heading. Add a default case to processList function
to handle the lists.

PR-URL: #5966
Fixes: #1545
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Robert Lindstädt <robert.lindstaedt@gmail.com>
Reviewed-By: Roman Reiss <me@silverwind.io>
MylesBorins pushed a commit that referenced this issue Apr 19, 2016
Doc tool produces incomplete json when it meets unordered lists that
directly following a heading. Add a default case to processList function
to handle the lists.

PR-URL: #5966
Fixes: #1545
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Robert Lindstädt <robert.lindstaedt@gmail.com>
Reviewed-By: Roman Reiss <me@silverwind.io>
MylesBorins pushed a commit that referenced this issue Apr 20, 2016
Doc tool produces incomplete json when it meets unordered lists that
directly following a heading. Add a default case to processList function
to handle the lists.

PR-URL: #5966
Fixes: #1545
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Robert Lindstädt <robert.lindstaedt@gmail.com>
Reviewed-By: Roman Reiss <me@silverwind.io>
MylesBorins pushed a commit that referenced this issue Apr 20, 2016
Doc tool produces incomplete json when it meets unordered lists that
directly following a heading. Add a default case to processList function
to handle the lists.

PR-URL: #5966
Fixes: #1545
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Robert Lindstädt <robert.lindstaedt@gmail.com>
Reviewed-By: Roman Reiss <me@silverwind.io>
jasnell pushed a commit that referenced this issue Apr 26, 2016
Doc tool produces incomplete json when it meets unordered lists that
directly following a heading. Add a default case to processList function
to handle the lists.

PR-URL: #5966
Fixes: #1545
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Robert Lindstädt <robert.lindstaedt@gmail.com>
Reviewed-By: Roman Reiss <me@silverwind.io>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations. good first issue Issues that are suitable for first-time contributors.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

5 participants