ankitskvmdam / clean-jsdoc-theme Goto Github PK

Describe the bug

A I can see in version 3.0.0 you have added a few options that can be useful, notably the theme configuration option "include_js_files". The problem is that, when trying to use this key it doesn't seem to have any effect. No copy of the file I indicate, no insertion of a <script> tag anywhere, just nothing. (I'm not sure of what should be the exact behavior as both the documentation and the changelog don't state it precisely, but I would expect it to try to do something...)

After searching in the code of this project that specific key doesn't seem to appear anywhere aside the documentation. So yeah, except if I miss something it looks like something which is cited in the documentation but not actually implemented.

To Reproduce

Try to do something using the "include_js_files" theme option in any project.

Expected behavior

That it does something.

Sometimes it is not required to show search, so it is better if there is an option to hide.

It would be nice if the search list close after clicking on any item or anywhere.

Describe the bug

Within my current typescript project I am using a jsdoc.js Javascript file type as opposed to the default jdsoc.json JSON file type. I'm also using npm packages eslint + prettier/recommended and typescript-eslint/recommended plugins.

There is an error to do with theme_opts and subsequent options keys, caused by the underscore characters in the key names violating the typescript-eslint camelCase rule when the key names are NOT enclosed in quote characters.

The following theme options keys violate the above mentioned rule (and probably many other style guides):

opts.theme_opts
opts.theme_opts.create_style
opts.theme_opts.add_style_path
opts.theme_opts.add_scripts
opts.theme_opts.add_script_path

They can be found in this repos publish.js file

To Reproduce

Use this theme:

• within a Typescript project.
• with npm packages: prettier/recommended + eslint + typescript-eslint/recommended
• with a jsdoc.js Javascript file type as opposed to the default jdsoc.json JSON file type.

Expected behavior

The theme options not to violate the typescript-eslint camelCase rule.

Additional context

If I enclose the key names in quote characters in order to rid myself of the typescript-eslint rule violation, this then violates the prettier/recommended rules and I'm still left with an error.

Either way I'm forced to enclose the key names within quotes and add eslint-disable-next-line above each of them.

There are some possible pros and cons to implementing a fix for this issue:

• Pros:

  • Removing the underscore characters in the theme options found in publish.js will make this theme eslint compatible (when using with a jsdoc.js Javascript file type) .
  • Easy modification to the publish.js file

• Cons:

  • Depending on implementation of modifying the publish.js file, there is the possibility of causing a breaking change. Users would be forced to update their existing jsdoc config files if the bugfix implementation is not backwards compatible.

I plan on forking this repo to implement a modified publish.js file for my personal project. Are you open to pull requests if I can implement a fix? I believe I can make it backwards version compatible.

P.S. Love the theme and your work so far. It's my favorite of all the themes I've tried.

Is your feature request related to a problem? Please describe.

I am attempting to link to external resources via the jsdoc examples, i.e.;

/**
 * The jQuery plugin namespace.
 * @external "jQuery.fn"
 * @see {@link http://learn.jquery.com/plugins/|jQuery Plugins}
 */

Describe the solution you'd like

The built in template that comes with jsdoc provides a link to the external resource

whereas it appears this is ignored within this template

Describe alternatives you've considered

I have tried implementing this through alternate jsdoc tags, but to no avail...and if I had a greater knowledge of how to customize the templates, I would submit a PR, but being so new to jsdoc I am not aware of any other solution

Additional context

If you could point me in the right direction, I could try my hand at submitting a PR for this, but I would need some assistance getting started

Describe the bug

Due to large code base search function has to search for a large array and this make the website un-usable.

To Reproduce
Generate a doc on the large codebases, like https://github.com/googleapis/nodejs-dialogflow use this to generate docs and try to use search.
Steps to reproduce the behavior:

1. Generate the docs
2. Open index.html
3. Try to search anything

Expected behavior

We will able to search whatever we want

Desktop (please complete the following information):

• OS: [e.g. Windows] Windows, macOs, Linux
• Browser [e.g. chrome, safari, firefox] chrome, safari, firefox, edge, brave, opera
• Version [e.g. 22]: 3.2.2

Smartphone (please complete the following information):

• Device: [e.g. iPhone6]: OnePlus 5
• OS: [e.g. iOS8.1]: Android
• Browser [e.g. stock browser, safari]: chrome
• Version [e.g. 22]: 3.2.2

Describe the bug

Fatal error when trying to generate the document.

To Reproduce

Steps to reproduce the behavior:
Theme installed locally through npm install --save-dev
jsdoc -t 'node_modules/clean-jsdoc-theme' 'code.js'

Expected behavior

JSDoc regular output

Screenshots

Desktop (please complete the following information):

• OS: Windows
• Browser N/A
• Version [e.g. 22]

Smartphone (please complete the following information):

• Device: [e.g. iPhone6]
• OS: [e.g. iOS8.1]
• Browser [e.g. stock browser, safari]
• Version 3.2.7

Additional context

Problem happens if using npm run or the conf.js "theme" option for JSDoc

Example:

Is your feature request related to a problem? Please describe.

It would be nice to be able to include the version of the documented code and some details about the doc creation in the footer.

Describe the solution you'd like

Something like "footer": "doc for {package.version} created on {creation.date}" in the config.

Describe alternatives you've considered

None.

Additional context

None.

When using @fires layout breaks. Doesn't happen when I do not use @fires in my comments.
See attached screenshot.

Because of w-100 class most probably the layout breaks.

Currently, there is no style. Add some style to search list container.

If there is an unsuccessful search that it must show that no result found but currently we didn't get such message.

• Add automatic builds and tests
• Add automatic releases to npm
• Add build status to README
• Add code coverage

Hello im trying to configure some css in my docs, and im trying to setup some colors and custom fonts. It is my code:

body { font-family: "Airbnb Cereal App", "Airbnb Cereal App Book"; } nav { background: linear-gradient( 180deg, rgb(3, 136, 163) 30%, rgb(0, 195, 116) 90% ); } h1.page-title::after background-color: rgb(0, 195, 116); } ...

and there is the clean-jsdoc-theme config:

"opts": { ... "theme_opts": { ... "add_style_path": ["./index.css"] }

when i run the code seems that its not working fine, what is wrong? can you fix that issue please?

It would be nice if we can add meta data like title, keywords or description.

We are not able to see search result of global functions.

@example code could provide a link to online editors using their post API, see for example stackblitz post-api or codepen prefill.

It would be nice to be able to fold main sections ('Classes', 'Modules', 'Externals'...) for projects that have a large number of classes, modules...

Need some extra left padding when rendering lists from README.md

Example :

There must be some separating line between two function function description.

I tried generating some docs with this file:

/**
 * @module My Module
 */

/**
 * Foo
 * @param name
 */
function foo(name) {
  console.log(`hello world ${name}`);
}

In the generated html, in the sidebar, if I click on My Module, it works fine and takes me to the proper page. But if I click on the nested item below that, foo, I get a 404.

I did a bit of experimentation and removed the space My Module > MyModule and now the foo link works properly.

I'm wondering if this is a requirement, like a requirement for no spaces within functions?

Currently its set at 250px by default, is there an option to set this to make it more wider? I tried looking into the css and changing the width myself, but it doesn't make the main content move, i.e. the sidebar gets wider but covers the docs

Is your feature request related to a problem? Please describe.

To append a list of extra links at the navbar is a great feature. But sometimes, to have those links at the bottom of all the navbar items makes more sense, for example, reference links. They are good to have but they are not the most important information needed to provide.

Describe the solution you'd like

Add an additional option called menuLocation, which accepts "up" or "down" as input.

{
    menu: menuArray,
    menuLocation: 'down'
}

Describe alternatives you've considered

Change the menu array as a big object to contain both the array and other options (if any).

{
    menu: {
        contents: menuArray,
        location: 'down'
    }
}

Additional context

Please check the PR, thanks.

Describe the bug

Note sure if is a bug, but the font of the returned type seems big, see for example here in your demo.

It would be nice if only the sidebar list scroll and sidebar title and search box remain fix.

Describe the bug

I don't know if this is described as a bug but in my previous issue I asked if there is a way to remove the source tags and there was a new update on the package that sort of added that feature there are still some source tags in the documentation of my code.

To Reproduce

Steps to reproduce the behavior:

1. Write a class or something.

2. Add a property to the class and add This jsdoc comment on top of it
   /** * Some description. * @default null * @type { String } */

Expected behavior

It should not add a source tag.

Screenshots

Desktop:

• OS: Windows
• Browser: Brave
• Version: 3.0.10

Is your feature request related to a problem? Please describe.

It would be nice to have a link to the source code from all documented elements, as in this example (see the constructor).

Describe the solution you'd like

Add an option to include or not source links.

Describe alternatives you've considered

None.

Additional context

None.

Is your feature request related to a problem? Please describe.

Because I'm documenting many classes/modules with several functions/methods, I'd like to be able to "close" classes/files in the left side index of functions.

Example: https://agentscript.org/docs/
The top class is AgentArray. I'd like to close it by clicking on the name, an accordion style action.

Ditto for the rest of the top level classes/modules.

Describe the solution you'd like

Clicking on a top level item closes it, showing only the top level name. I think "accordion" is the css term.

Describe alternatives you've considered

Possibly separate pages per top level group. So the left hand side has links to the separate page.

Not sure how to do this with jsDoc.

Additional context

I think the url above should do the trick.

And I gotta THANK YOU for this terrific tool. Wow!

When have an image whose width is large then there is overflow

Need an alternative to native scrollbars. OverlayScrollbars are a good alternative.

There must be an option to add the link of the font and use it.
We have to create an option: fonts which is an array of an object like:

"fonts": [
 {
   "link": "https://fonts.googleapis.com/css?family=Hind&display=swap",
    "name": "font name",
    "target": "body" // It can be, body, heading or code
 }
]

body: font which is used in paragraph, sidebar.
heading: font which is used in heading.
code: font which is used in code.

It would be nice if we have a menu sidebar like a link to the project website and other options. We can include an option for the menu which accepts an array of menu items like.

"menu": [
{
"title": "Website",
"link": "https://example.com",
"target": "_blank",
"class": "some-class",
"id": "some-id"
}
]

We are planning to use fuse.js

Documentation: https://fusejs.io/

Describe the bug

When a member has a @default or @defaultvalue tag, the closing div of the HTML description is malformed (specifically, it looks like this: </div)

To Reproduce

1. Clone my fork
2. Run npm i && npm run doc:issue
3. Open the generated @default-tag-issue/doc/CSS.html file in vim (or some other editor)
4. Using vim, enter :g/.<\/div$, or type .<\/div$ into your editor's search box with regular expressions activated
5. There will be 4 matches, around lines 146, 220, 294, 368 (see screenshots below)

Expected behavior

@default metadata should render as valid HTML.

For now, the problem can be fixed by removing all @default and @defaultvalue tags from the JSDoc markup; users should be advised not to use these tags until the bug is patched.

Screenshots

Using the @default tag . . .

. . . produces HTML like this:

. . . in every place where the @default tag is encountered:

. . . which breaks the layout:

Desktop

• OS: Debian Buster 10.5
• Browser Firefox
• Version 82.0.3
• clean-jsdoc-theme version 2.2.13

Additional context

• it behaves the same with the @defaultvalue alternative tag as with @default
• same results using the light or dark theme