mattmcmanus / dox-foundation

HTML output for Dox documentation generator

Hey friend 👋

I wrote my first HTML and CSS in 2001 and I've been living the webmaster's dream ever since. 😎

dox-foundation's Issues

Menu doesn't link to the file.

FOr example, I have a file like

/*
 * LICENSE
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 */

import Modifier from 'famous/core/Modifier';
import RenderNode from 'famous/core/RenderNode';
import TransitionableTransform from 'famous/transitions/TransitionableTransform';
import EventHandler from 'famous/core/EventHandler';

import "army-knife/polyfill.Function.name";

/*
 * The Molecule is the basic building block of all components.
 * @class
 */
class Molecule extends RenderNode {
    constructor(initialOptions) {
      /* ... */
    }
}
export Molecule
export default Molecule;

The menu shows no links for this file because it doesn't have any function docs to link to, but there should at least be a way to link to the file's page somehow. Perhaps a link symbol next to the name or something.

Update layouts to use Foundation 4

Foundation 4 (http://foundation.zurb.com/docs) is the hotness

Change the root folders that get served?

It seems like dox-foundation generates docs in the target folder in a structure that is the same things it sees relative to it's working directory. FOr exmple

dox-foundation --source src --target docs

expects the server to serve the working directoy, but a better behavior would (or at least the ability to choose the behavior) would be to assume the docs folder will be served.

Also, I'd like the root of the source to be considered as src not the working directory.

So currently do

dox-foundation --source src --target docs
serve

but I'd rather do

dox-foundation --source src --target docs
serve docs

And for file src/file.js I don't want to visit /src/file.js.html in the browser, I just want to visit /file.js.html. The reason is that usage of my files are like var foo = require('file') not var foo = require('src/file'), so I'd like to reflect that in the url structure.

support for folders

nice project! is there any way to parse a whole folder ?

Idea: Show the package's README.md on the index page

instead of a blank page.

Request: Add support for custom tags

I currently use a more phpDoc -style when I am documenting inline code , and also use my own custom tags:

/**
 * Title
 *
 * Description
 * 
 * @file (what's the files name?)
 * @author (who's the author)
 * @calls (what methods do this method call?)
 * @source (where is the data coming from? )
 */

bug: Comment tags show raw HTML markup and other stuff.

For example:

Hidden functions are shown for non-selected files in sidebar nav

In the projects I use dox-foundation for, I tend to have many files with hidden private functions in each. To prevent private methods from being rendered in the docs, I use the /*!*/ convention in the comment header. As of version 0.5.0, there is an issue with displaying hidden methods' names when expanding the API preview of a non-selected file. To reproduce, look at a project with multiple files and hidden functions throughout. I have a sample currently available here. Look at any function's documentation on the first page, and expand another page with hidden functions in the navigation (but do not actually click on a function name to follow the link). From here you can see functions that should be hidden. Clicking on any of the function names will follow the link, and from there the hidden functions will actually be hidden, as expected.

Hopefully that makes sense. I'm happy to clarify if it doesn't.

Here are some screenshots.

Thanks!

Multiple files with same name in different subdirs all are active

When there are multiple files with the same name, but in different subdirectories, all are rendered active. See attached image for example.

Generated menu is too long when you generated a lot of files

When generating docs for huge number of files, the left side menu is spanning below the viewport, this is especially irritating when the left side menu is position:fixed

Cleanup up rendered html. It's gross right now.

Everything is inline at the moment. I think it should stay that way but it's messy.

What type of comments are supported?

All of jsdoc syntax? For example @class?

Twistie for show/hide code & example elements

It would be great if dox-foundation supported a twistie which would allow the user to show or hide the actual function code and examples.

For example, each of the

<pre>
  <code>
...
  </code>
</pre>

blocks which contains the actual source code and example code could have a clickable text heading to show/hide the respective block of code.

If this enhancement was implemented IMO it would make sense to initially have each of the blocks hidden, so the page was compressed and easy to navigate as with sizable pages. The user could then click the 'show code' or 'show example' to expand the respective section and view the source.

With multiple levels of folders, links break when you are viewing a file in a sub folder

Say your structure is

-- file1.html
-- file2.html
-- folder
   |-- file3.html

When you are viewing the file3 in the folder, all the links break. Right now they are relative and assuming a single level of files ie: href="file1.html".

Basically, the nav needs to be aware of how deep it is. If it's at level 0, carry on. If it's one level down, then prepend ../ on each link. Level 2, ../../, and so on

relative pathes for links

I have the two directories "foo" and "docs". Inside of "foo" is the file "foo.js". I call

dox-foundation --source foo --target docs

and get

docs/foo.js.html
docs/index.html

This structure is working as long as the directory is not moved or e.g. installed inside a database like "couchdb". The reason is: "dox-foundation" wites absolute (!) pathes to "index.html". This is bad. In the example I see

"/home/niepra01/tmp/docs/foo.js.html"

as link target instead of

"docs/foo.js.html".

Greetings from Berlin

...Rolf

-i flag -- does this replace or extend?

If I use the -i flag, is it used instead of the defaults or is it added to the defaults? The README is ambiguous here.

Update templates to use cdnjs for all external libraries

http://cdnjs.com/

This will keep the templates lean and avoid unnecessary duplication of code when a project generates a lot of different files

target option is not optional

It is specified that target option has default value. So it seems that the option can be omitted. But in fact the option should be specified because the following command throws the error Arguments to path.resolve must be strings:
dox-foundation --source ./some.js

Idea: Let tags take precedence over dox's code ctx.

See here for example: tj/dox#144

Request: Add option for full TOC

With that I mean:

Make an option / set default the possibility to have a link meny on the generated html left hand side with links to files that are doxxed/methods. Currently, it seems that only the variables starting with "_" ( like _service is displayed in the generated documentation file.

Error while running: dox-foundation.js:32 - files Object has no method 'map'

$ dox-foundation < Desktop.js > desktop_dox.html

/usr/lib/node_modules/dox-foundation/lib/dox-foundation.js:32
    options.structure = files.map(function(file){
                              ^
TypeError: Object #<Object> has no method 'map'
    at Object.exports.parse (/usr/lib/node_modules/dox-foundation/lib/dox-foundation.js:32:31)
    at null.<anonymous> (/usr/lib/node_modules/dox-foundation/bin/dox-foundation:96:30)
    at EventEmitter.emit (events.js:85:17)
    at afterRead (fs.js:1324:12)
    at Object.wrapper [as oncomplete] (fs.js:362:17)

BUG: for loop with no spaces creates bad HTML output

This line in my projects code breaks the html when doxxed:

for(var i=0;i<series.length;i++)

When I add spaces before and after the < char it works:

for(var i=0;i < series.length;i++)

Dox-foundation can't find generated file before writing to it..

Current outcome

C:\Users\QE1\Workspace\app>node_modules\grunt-dox\node_modules\.bin\dox-foundation --source C:\Users\QE1\Workspace\company\fpi_client\js\src\ --target C:\Users\QE1\Workspace\company\fpi_client\js\docs\ --title "Client"

fs.js:338
  return binding.open(pathModule._makeLong(path), stringToFlags(flags), mode);
                 ^
Error: ENOENT, no such file or directory 'C:\Users\QE1\Workspace\company\fpi_client\js\docs\api.js.html'
    at Object.fs.openSync (fs.js:338:18)
    at Object.fs.writeFileSync (fs.js:756:15)
    at C:\Users\QE1\Workspace\app\node_modules\grunt-dox\node_modules\dox-foundation\bin\dox-foundation:83:8
    at Array.forEach (native)
    at Object.<anonymous> (C:\Users\QE1\Workspace\app\node_modules\grunt-dox\node_modules\dox-foundation\bin\dox-foundation:78:9)
    at Module._compile (module.js:449:26)
    at Object.Module._extensions..js (module.js:467:10)
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:312:12)
    at Module.runMain (module.js:492:10)

It seems like it expects api.js.html to be found.

[BUG] For some reason the "methods" array comes out empty. Doc navigation is empty, doc headers empty.

Sometimes dox-foundation is working, sometimes it's not. I can't yet pinpoint why. When it works, the method names appear in the sidebar, and docs look as expected. When it fails, the menu items for each file are empty because the methods array is empty. And the docs for the pages are likewise missing that information.

To reproduce, I can clone my repo infamous, go into the root of the repo, then run dox-foundation --source src and the result will (probably) have this problem. I also tried cloning dox-foundatio, updating it's package.json to use the latest version of dox, then then installed that local version of dox-foundation, and the results are similar, but a few things erroneous things show up in the menu.

What might be happening here? Have I done my documentation properly?

function links with ../../

I just installed the latest version 0.5.2 and realized that the links in the sidbar go two levels above the point where index.html lives.

Example: the index.html url is:

   http://localhost:5984/vaclab_db/_design/yamp/src_doc/index.html

the e.g. the first function (yamp_worker) in the sidebar links to:

  http://localhost:5984/vaclab_db/src_doc/yamp.worker.js.html#yamp_worker

but has to be:

  http://localhost:5984/vaclab_db/_design/yamp/src_doc/yamp.worker.js.html#yamp_worker

It looks for me that there is a uncorrect ../../ somewhere.

thank you & regards

Used required module findit has poor support for Windows.

require('findit').findSync(source)

This will only result in returning ONE file in the given source directory.. I suggest you find another module for this, or create your own directory walker with fs.readdirSync

-t flag -- what does it do?

I don't understand from the README what the -t flag is for

Add filter buttons for declarations, properties and function

Simple buttons at the top right of the page that will quickly allow you to filter the page options to just declarations, properties or function.

Make this so it can easily be extended to allow for other types of properties.

dox-foundation --help (or any other invocation) fails with ENOENT

fs.js:338
return binding.open(pathModule._makeLong(path), stringToFlags(flags), mode);
^
Error: ENOENT, no such file or directory 'views/template.jade'
at Object.fs.openSync (fs.js:338:18)
at Object.fs.readFileSync (fs.js:182:15)
at Object. (node_modules/dox-foundation/lib/dox-foundation.js:7:20)
at Module._compile (module.js:449:26)

spurious number

"dox-foundation" produces a spurious number in the upper left corner of the html page. Small example:

echo -e '/**\n * @param x\n */\nfunction foo(x){\nreturn x};\n' | \
  dox-foundation > xx.html

Before "" as the first character in the html code you can see the number "1". It's not a big problem, but...

Greetings from Berlin

Rolf

Omit function source

It would be nice if we could use dox-foundataion to build a 'public' API of a private codebase, that is without including the source code.

Syntax highlighting for Examples

It would be great if dox-foundation supported syntax highlighting for 'Examples' generated by dox... More details below.

Using dox, you can provide examples:

/**
 * Escape the given `html`.
 *
 * Examples:
 *
 *     utils.escape('<script></script>')
 *     // => '&lt;script&gt;&lt;/script&gt;'
 *
 * @param {String} html string to be escaped
 * @return {String} escaped html
 * @api public
 */

In the HTML code produced, the 'Examples' end up in a code element:

<pre>
    <code>
      // Example code here
      // ...
    </code>
</pre>

However this element is not syntax highlighted as per dox-foundation... It would great if the examples where highlighted in addition to the actual implementation.

Cannot find module

Howdy!

When I run:

dox-foundation --source myFolderOJavaScript --target docs

I get the following error:

module.js:340
throw err;
^
Error: Cannot find module '/Users/began/workspace/abu/frontend/rebar/js/package'
at Function.Module._resolveFilename (module.js:338:15)
at Function.Module._load (module.js:280:25)
at Module.require (module.js:362:17)
at require (module.js:378:17)
at Object. (/usr/local/lib/node_modules/dox-foundation/bin/dox-foundation:74:29)
at Module._compile (module.js:449:26)
at Object.Module._extensions..js (module.js:467:10)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:312:12)
at Module.runMain (module.js:492:10)

When I manually edited /usr/local/lib/node_modules/dox-foundation/lib/dox-foundation.js, I removed line 11:

pkg = require('../package'),

And then replaced:

exports.name = pkg.name;

with

exports.name = "dox-foundation";

and

exports.version = pkg.version;

with

exports.version = "0.4.2";

It all worked fine. Not sure how best to fix this ,but wanted to submit a bug report and how I fixed it on my end.

Thanks!
Brian

doctype html + css not working

A freshly installed copy of dox-foundation (from npm) doesn't work. I suspect this is due to a new version of jade. Error is:

dox-foundation < myfile.js > myfile.html                                                                                                                                 

/usr/local/lib/node_modules/dox-foundation/node_modules/jade/lib/runtime.js:200
  throw err;
        ^
Error: /usr/local/lib/node_modules/dox-foundation/views/template.jade:73
    71| 
    72|     include ./_footer.jade
  > 73| 

`doctype 5` is deprecated, you must now use `doctype html`

I edited the offending file and corrected the doctype issue. However the produced html still doesn't work.

subTitle is not defined

I got the error message in the suject on a fresh installed system:
dox-foundation < dox-test.js
wherby dox-test.js is

 /*
  * valStat
  * @param x 
  * @return res 
  */
 vlStat = function(x){

     if (x && x.length > 2){
     ...
     }
 };
 exports.vlStat = vlStat;

I have the version (installed over npm) 0.0.1

Floating side nav support

IMHO - the HTML generated from dox-foundation would be more user friendly if the nav list (function list side-nav) was floating (i.e. fixed). For example if I've generated a fairly lengthy document and am view it, I have to scroll up (or search) if I want to locate a different function. I think it would make for a better experience if the side nav floated down with the page scroll.

Add support for multiple paths in --source flag

From what I see in the docs and code, you can't pass multiple paths to dox-foundation:

I would like this to work:

$ dox-foundation --source "<folder1>, <folder2>, <filepath>, <folder3>" --target <path to target>

Tried to manipulate the code myself to support it, but was more time consuming that I thought.

The only solution I see now to solve this without rewriting dox-foundation to support the outcome I require is to never have *.js-files in subdirectories..

Idea: A way to configure dox options.

Is there a way to configure what options dox uses?

Additional .md-File, Order of files

Hi there, great tool, easy to use and astonishing output! I wonder if there is a way to add an introducing (readme.md) file or to determine the order of files if the input directory in the outputted html files? As far as I understand only .js files are parsed and the order seems random?