|
| 1 | +@page high-level-overview High Level Overview |
| 2 | +@parent guides 0 |
| 3 | + |
| 4 | +Loosely based on ideas and lessons learned from [DocumentJS](http://documentjs.com), bit-docs is an evolving set of tools that allow you to: |
| 5 | + |
| 6 | + - Write documentation inline, or in markdown files. |
| 7 | + - Specify your code's behavior precisely with JSDoc |
| 8 | + and [Google Closure Compiler](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler) |
| 9 | + annotations. |
| 10 | +- Generate a ready-to-publish website from that documentation. |
| 11 | + |
| 12 | +The `bit-docs` tool (this repo) orchestrates "finder" plugins that slurp in raw data with "processor" and "generator" plugins that spit out structured documents from that data. The `bit-docs` tool sits happily between such plugins, automating their install and cooperation. |
| 13 | + |
| 14 | +Depending on the plugins used, input may be in the form of inline code comments, markdown files, or anything else you could imagine; output may be in the form of HTML, or any other format. |
| 15 | + |
| 16 | +You could write "finder" and "generator" plugins for the `bit-docs` tool geared towards static site generation for a blog or generic website, but `bit-docs` is particularly useful for generating documention websites from and for code projects. |
| 17 | + |
| 18 | +### Projects currently using bit-docs |
| 19 | + |
| 20 | + - [CanJS](https://github.com/canjs/canjs) — [Generated website](http://canjs.com) |
| 21 | + - [StealJS](https://github.com/stealjs/stealjs) — [Generated website](http://stealjs.com) |
| 22 | + - [DoneJS](https://github.com/donejs/donejs-next) — [Generated website](https://donejs.github.io/donejs-next) |
| 23 | + |
| 24 | +### Usage |
| 25 | + |
| 26 | +It is possible to add the bit-docs package as a dependency to the actual project you wish to document, but we have found creating an entirely new dedicated repository that will pull in the codebase(s) that you wish to document is a better paradigm. So, for `your-project` you might create a new repository called `your-project-site`. |
| 27 | + |
| 28 | +This paradigm of creating a repository dedicated to generating documentation with bit-docs is especially useful when pulling in multiple codebases and wishing to generate a unified website. This is the strategy used by StealJS and DoneJS to document their core functionality and the functionality of their various modules that are broken out into separate repos and packages! |
| 29 | + |
| 30 | +To use bit-docs, add it to the `package.json` of the project you want to use it in: |
| 31 | + |
| 32 | +``` |
| 33 | +npm install bit-docs --save-dev |
| 34 | +``` |
| 35 | + |
| 36 | +Next, in your project's `package.json`, add a section called `bit-docs`, like: |
| 37 | + |
| 38 | +``` |
| 39 | + "bit-docs": { |
| 40 | + "dependencies": { |
| 41 | + "bit-docs-glob-finder": "*", |
| 42 | + "bit-docs-dev": "*", |
| 43 | + "bit-docs-js": "*", |
| 44 | + "bit-docs-generate-html": "*" |
| 45 | + }, |
| 46 | + "glob": { |
| 47 | + "pattern": "docs/**/*.{js,md}" |
| 48 | + }, |
| 49 | + "parent": "indexfile", |
| 50 | + "minifyBuild": false |
| 51 | + } |
| 52 | +``` |
| 53 | + |
| 54 | +If you created a new repo specifically to hold this bit-docs stuff, you may wish to add the codebases you will be documenting as normal `package.json` devDependencies at this time. You will need to update the `bit-docs` glob pattern to be similar to what the StealJS website repo does (to tell the glob finder to look in `node_modules` for files to process): |
| 55 | + |
| 56 | +``` |
| 57 | + "glob": { |
| 58 | + "pattern": "{node_modules,doc}/{steal,grunt-steal,steal-*}/**/*.{js,md}", |
| 59 | + "ignore": [ |
| 60 | + "node_modules/steal/test/**/*", |
| 61 | + "node_modules/steal-tools/test/**/*", |
| 62 | + "node_modules/steal-conditional/{demo,test,node_modules}/**/*" |
| 63 | + ] |
| 64 | + }, |
| 65 | +``` |
| 66 | + |
| 67 | +Under the hood, bit-docs uses `npm` to install the `dependencies` defined under the `bit-docs` configuration in `package.json`. However, instead of installing packages into your project's top-level `node_modules`, bit-docs utilizes npm to install plugin packages to it's own directory: |
| 68 | + |
| 69 | +``` |
| 70 | +./your-project/node_modules/bit-docs/lib/configure/node_modules |
| 71 | +``` |
| 72 | + |
| 73 | +Maintaining this nested `node_modules` directory gives `bit-docs` complete control over this subset of plugin packages, enabling things like the `-f` "force" flag to completely delete and reinstall the plugin packages. The force flag is particularly useful after updating the dependency list to remove a plugin package that has previously been installed (otherwise, that old dependency won't be removed from the nested `node_modules` and will still be included by bit-docs). |
| 74 | + |
| 75 | +Look at the `.gitignore` of this repo; you'll notice an entry for `lib/configure/node_modules/`, and entries for other directories that will be generated on the fly when `bit-docs` is run. |
| 76 | + |
| 77 | +Utilization of npm under the hood means things like the `file://` syntax for `dependencies` in the `bit-docs` configuration is fair game, which can be useful for local debugging of bit-docs plugins. |
| 78 | + |
| 79 | +For more information on developing locally, see [`CONTRIBUTING.md`](CONTRIBUTING.md). |
| 80 | + |
| 81 | +### Plugins |
| 82 | + |
| 83 | +There are four handlers that any given bit-docs plugin can hook into using a standardized `bit-docs.js` file in the root of the plugin's directory. A plugin could hook into all four of these actions at once but, following the unix philosophy, bit-docs plugins should strive to do one thing only, and do it well. Therefore, most plugins will only hook into one (or two) of these handlers to accomplish their intended task, but probably never all four. |
| 84 | + |
| 85 | +#### Finder |
| 86 | + |
| 87 | +Plugins that hook into the `finder` handler affect how bit-docs searches for source-files. |
| 88 | + |
| 89 | +The default finder supports glob syntax, and should be sufficient for most use-cases: |
| 90 | + |
| 91 | +- <https://github.com/bit-docs/bit-docs-glob-finder> |
| 92 | + |
| 93 | +You might need to create a plugin that hooks into the `finder` handler if you're pulling source from a database, or some other location that's not the current working filesystem. |
| 94 | + |
| 95 | +#### Processor |
| 96 | + |
| 97 | +Plugins that hook into the `processor` handler may augment how found files are processed. |
| 98 | + |
| 99 | +The following plugin is always included by default in the core of bit-docs: |
| 100 | + |
| 101 | +- <https://github.com/bit-docs/bit-docs-process-tags> |
| 102 | + |
| 103 | +This is because that plugin provides the extremely common task of processing "tags". A tag is an identifier, usually embedded in source code comments, that provides documentation or information about some functionality, inline in the source code itself. Some of the many default tags are `@@function @@parent @@description @@body`, used in a source-file like: |
| 104 | + |
| 105 | +```js |
| 106 | +/** |
| 107 | + * @@function yourproject.hellofunc hellofunc |
| 108 | + * @@parent YourProject.apis |
| 109 | + * @@description |
| 110 | +
|
| 111 | + * This documents something in a sub-page of YourProject. |
| 112 | + * |
| 113 | + * @@body |
| 114 | + * |
| 115 | + * ## Usage |
| 116 | + * |
| 117 | + * Explain how to use it in _markdown_! |
| 118 | + */ |
| 119 | +``` |
| 120 | + |
| 121 | +For an example of a processor plugin that's not included by default, see: |
| 122 | + |
| 123 | +- <https://github.com/bit-docs/bit-docs-process-mustache> |
| 124 | + |
| 125 | +#### Generator |
| 126 | + |
| 127 | +Plugins that hook into the `generator` handler output something from the processed data. |
| 128 | + |
| 129 | +For example, see these bit-docs plugins that output HTML files: |
| 130 | + |
| 131 | +- <https://github.com/bit-docs/bit-docs-generate-html> |
| 132 | +- <https://github.com/bit-docs/bit-docs-generate-readme> |
| 133 | + |
| 134 | +#### Tag |
| 135 | + |
| 136 | +Plugins that hook into the `tag` handler add new tags like `@@yourtag` to the default processing that bit-docs already does to source-file comments. |
| 137 | + |
| 138 | +For example, see these bit-docs plugins for prettifying source-code snippets: |
| 139 | + |
| 140 | +- <https://github.com/bit-docs/bit-docs-prettify> |
| 141 | +- <https://github.com/bit-docs/bit-docs-html-highlight-line> |
| 142 | + |
| 143 | +### Plugins that Hook into Other Plugins |
| 144 | + |
| 145 | +The previously mentioned `bit-docs-generate-html` is a "generator" plugin but also accepts hooks into itself, which allows the following plugin to add functionality to that plugin: |
| 146 | + |
| 147 | +- <https://github.com/bit-docs/bit-docs-html-toc> |
| 148 | + |
| 149 | +Take a look at `bit-docs-html-toc`'s [`bit-docs.js`](https://github.com/bit-docs/bit-docs-html-toc/blob/master/bit-docs.js) file to see how a plugin registers itself with another plugin. |
| 150 | + |
| 151 | +Find more plugins at the [bit-docs organization on GitHub](https://github.com/bit-docs). |
| 152 | + |
| 153 | +## Contributing |
| 154 | + |
| 155 | +Want to help make `bit-docs` even better? See [`CONTRIBUTING.md`](CONTRIBUTING.md). |
| 156 | + |
| 157 | +Looking for a changelog? Try the [releases page on GitHub](https://github.com/bit-docs/bit-docs/releases). |
0 commit comments