<commit_before>@page guides/contributing/documentation Improving the Docs & Site
@parent guides/contribute 6

@description Learn how to improve CanJS’s site and documentation.

@body

## Overview

The CanJS site is generated with [bit-docs](https://github.com/bit-docs/bit-docs),
a modified version of [DocumentJS](https://documentjs.com).  Its
content is hosted using GitHub pages publishing the [canjs/canjs#gh-pages](https://github.com/canjs/canjs/tree/gh-pages) repo.

`bit-docs` reads JavaScript comments and markdown files within the `canjs` repo as well as
the individual repositories within `node_modules` to produce a static site.

The high level content (Ex: homepage) and the guides content for the site is within the
`canjs/docs` folder.  Individual repositories contain their own markdown and commented
JavaScript files used to produce their API pages.

## Generate the documentation locally

First, follow the steps listed under [guides/contributing/developing-locally] to
fork & clone the repository, install the dependencies, build the documentation,
and view the site locally.

## Improve the theme’s design and styles

The CanJS theme is in
[bit-docs-html-canjs](https://github.com/canjs/bit-docs-html-canjs). Its
[README](https://github.com/canjs/bit-docs-html-canjs/blob/master/readme.md)
has instructions on how to test out the theme.  Once the theme is updated and published,

1. Open `canjs/package.json`. Update `bit-docs-html-canjs`’s version to the new theme version.
2. Run `npm run document:force` to make sure the theme is correctly applied.

The [CanJS design folder](https://drive.google.com/open?id=0B9uYesPecByGZGkzc2YxRHA4ZEE)
has logos, stickers, and other design resources.

## Test out content from other repos

As noted above, the API docs from each package come from that package.  So if you’re
improving the docs for say `can-compute`, you want to see what `can-compute`’s docs look like,
install your local `can-compute` and re-run bit-docs like:

```shell
npm install ../can-compute && npm run document:force
```


## Publish the documentation

Once the docs look right locally, commit your changes, then run:

```shell
make
```

The make script will generate the documentation again and push out the `gh-pages` branch.


## Writing API documentation

Our documentation is modeled off of jQuery’s.  Please read
their [guidelines](https://github.com/jquery/api.jquery.com/blob/master/README.md). Also read our
[guides/api].

Generally speaking there are three parts to every documentation page:

 - Its description<commit_msg>Remove `:force` from the `npm run document` command<commit_after>@page guides/contributing/documentation Improving the Docs & Site
@parent guides/contribute 6

@description Learn how to improve CanJS’s site and documentation.

@body

## Overview

The CanJS site is generated with [bit-docs](https://github.com/bit-docs/bit-docs),
a modified version of [DocumentJS](https://documentjs.com).  Its
content is hosted using GitHub pages publishing the [canjs/canjs#gh-pages](https://github.com/canjs/canjs/tree/gh-pages) repo.

`bit-docs` reads JavaScript comments and markdown files within the `canjs` repo as well as
the individual repositories within `node_modules` to produce a static site.

The high level content (Ex: homepage) and the guides content for the site is within the
`canjs/docs` folder.  Individual repositories contain their own markdown and commented
JavaScript files used to produce their API pages.

## Generate the documentation locally

First, follow the steps listed under [guides/contributing/developing-locally] to
fork & clone the repository, install the dependencies, build the documentation,
and view the site locally.

## Improve the theme’s design and styles

The CanJS theme is in
[bit-docs-html-canjs](https://github.com/canjs/bit-docs-html-canjs). Its
[README](https://github.com/canjs/bit-docs-html-canjs/blob/master/readme.md)
has instructions on how to test out the theme.  Once the theme is updated and published,

1. Open `canjs/package.json`. Update `bit-docs-html-canjs`’s version to the new theme version.
2. Run `npm run document` to make sure the theme is correctly applied.

The [CanJS design folder](https://drive.google.com/open?id=0B9uYesPecByGZGkzc2YxRHA4ZEE)
has logos, stickers, and other design resources.

## Test out content from other repos

As noted above, the API docs from each package come from that package.  So if you’re
improving the docs for say `can-compute`, you want to see what `can-compute`’s docs look like,
install your local `can-compute` and re-run bit-docs like:

```shell
npm install ../can-compute && npm run document
```


## Publish the documentation

Once the docs look right locally, commit your changes, then run:

```shell
make
```

The make script will generate the documentation again and push out the `gh-pages` branch.


## Writing API documentation

Our documentation is modeled off of jQuery’s.  Please read
their [guidelines](https://github.com/jquery/api.jquery.com/blob/master/README.md). Also read our
[guides/api].

Generally speaking there are three parts to every documentation page:

 - Its description
{'fraction_non_alphanumeric': 0.09011627906976744, 'fraction_numerical': 0.0027131782945736434, 'mean_word_length': 4.6589912280701755, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 14, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3432544', 'n_tokens_mistral': 1514, 'n_tokens_neox': 1448, 'n_words': 616}