docs/README.md

# README: Overview Documentation Repository

## How the Documentation is Organized


Directories that contain only content

<table>
  <tr>
    <th>Directory</th>
    <th>Purpose</th>
     <th>Technical Repo(s)</th>
  </tr>
  <tr>
    <td>_android</td>
    <td>SDK tutorial. Part of the <a href="https://github.com/blockstack/docs.blockstack/blob/master/_data/navigation_learn.yml">developer menu</a>.</td>
   <td><a href="https://github.com/blockstack/blockstack-android">https://github.com/blockstack/blockstack-android</a></td>
  </tr>
  <tr>
    <td>_browser</td>
    <td>Information for end-users about our identity, Storage, and using the browser. There are also three of the original tutorials in there. User docs controlled by in the the <a href="https://github.com/blockstack/docs.blockstack/blob/master/_data/navigation_usenew.yml">user menu</a>. The three tutorials that appear in the <a href="https://github.com/blockstack/docs.blockstack/blob/master/_data/navigation_learn.yml">developer menu</a> There is an <a href="https://github.com/blockstack/docs.blockstack/issues/501" target="_blank">outstanding issue</a> to move these.</td>
   <td><a href="https://github.com/blockstack/blockstack-browser">https://github.com/blockstack/blockstack-browser</a></td>
  </tr>
  <tr>
    <td>_common</td>
    <td>Contains several shell files that redirect to our reference documentation sites such as Javascript, IOS, and so forth.  The reference docs are linked from the developer, core, and Gaia menus.</td>
    <td>Each of these references are generated by their respective repos, core.blockstack.org from <code>blockstack-core</code>, Javascript docs from the <code>blockstack.js</code> and so forth.</td>
  </tr>
  <tr>
    <td>_core</td>
    <td>Information for wallet, blockchain, or Clarity developers -- including Atlas, BNS, and so forth. <b>This content STILL needs to be synced with the master docs subdirectory in <a href="https://github.com/blockstack/blockstack-core/tree/master/docs" target="_blank">blockstack-core</a>.</b></td>
    <td> <a href="https://github.com/blockstack/blockstack-core/tree/master/docs" target="_blank">blockstack-core</a></td>
  </tr>
  <tr>
    <td>_develop</td>
    <td>Information for application miners covers using the Javascript library, our mobile SDKs, and the concepts hat support them. Navigation controlled by <a href="https://github.com/blockstack/docs.blockstack/blob/master/_data/navigation_learn.yml">developer menu</a> </td>
    <td>This information was never associated with a single repo. Much of it does rely heavily on<a href="https://github.com/blockstack/blockstack.js">https://github.com/blockstack/blockstack.js</a>.</td>
  </tr>
  <tr>
  <td>_includes</td>
    <td>Information reused (markdown or html) in many places, common html used in pages and notes.</td>
    <td></td>
  </tr>
    <tr>
    <td>_ios</td>
    <td>SDK tutorial. Part of the <a href="https://github.com/blockstack/docs.blockstack/blob/master/_data/navigation_learn.yml">developer menu</a>.</td>
    <td><a href="https://github.com/blockstack/blockstack-ios">https://github.com/blockstack/blockstack-ios</a></td>
  </tr>
  <tr>
    <td>_org</td>
    <td>Information for Stacks holders and people curious about what Blockstack does. User docs controlled by in the the <a href="https://github.com/blockstack/docs.blockstack/blob/master/_data/navigation_org.yml">organization menu</a></td>
    <td>Not associated with any repository.</td>
  <tr>
    <td>_storage</td>
    <td></td>
       <td><a href="https://github.com/blockstack/blockstack-gaia">https://github.com/blockstack/blockstack-gaia</a></td>
  </tr>
  </table>

<table>
  <tr>
    <th>Directory</th>
    <th>Purpose</th>
     <th>Notes</th>
  </tr>
  <tr>
    <td>_common</td>
    <td></td>
    <td></td>
  </tr>
  <tr>
    <td>_data</td>
    <td></td>
    <td></td>
  </tr>
  <tr>
    <td>_faqs</td>
    <td></td>
    <td></td>
  </tr>
  <tr>
  <td>_includes</td>
    <td></td>
    <td></td>
  </tr>
<tr>
    <td>_layouts</td>
    <td></td>
    <td></td>
</tr>
   <tr>
    <td>_plugins</td>
    <td></td>
    <td></td>
  </tr> 
  <tr>
    <td>_posts</td>
    <td></td>
    <td></td>
  </tr>
  <tr>
    <td>_sass</td>
    <td></td>
    <td></td>
  </tr>
 <tr>
    <td>assets</td>
    <td></td>
    <td></td>
  </tr>
  <tr>
    <td>exclude</td>
    <td></td>
    <td></td>
  </tr>
  </table>



## 

## Run locally

To run locally:

1. Get the content from the downstream repos.

    ```
    ./get-content.sh
    ```

3. Build and serve locally.

   ```
   bundle exec jekyll serve --config _config.yml,staticman.yml
   ```

   Use this format to turn on production features:

   ```
   JEKYLL_ENV=production bundle exec jekyll serve --config _config.yml
   ```

## Deploy via Netlify

To deploy to Netlify:

1. Build the site.

    ```
    JEKYLL_ENV=production bundle exec jekyll build --config _config.yml
    ```
2. Force add the `_site` directory.

    ```
    git push -f origin
    ```

## Test a Deploy with Surge


```
cd _site
surge
```

```
surge --domain raspy-songs.surge.sh
```

# To generate the CLI json manually

The `_data/cliRef.json` file is generated from the `blockstack-cli` subcommand `docs`. This data file is consumed by the `_includes/commandline.md` file which is used to serve up the reference.  

1. Install the latest version of the cli according to the instructions at: https://github.com/blockstack/cli-blockstack

2. Generate the json for the cli in the `docs.blockstack` repo.

   ```
   $ blockstack-cli docs | python -m json.tool > _data/cliRef.json 
   ```

3. Make sure the generated docs are clean by building the documentation.

   If you run into any problem in the generation usually it results from a problem in the repo. You can make a pull request back to the repo to fix anything.

## Clarity Reference

As of 8/12/19 Clarity is in the [develop](https://github.com/blockstack/blockstack-core/tree/develop) branch of core.  You can build the Clarity command line from the Docker image. `core/src/vm/docs/mod.rs`


1. Pull the latest developer preview from the Docker Hub.

   ```
   $ docker pull blockstack/blockstack-core:clarity-developer-preview
   ```

2. Build the lastest JSON.

   ```
   docker run -it blockstack/blockstack-core:clarity-developer-preview blockstack-core docgen | jsonpp > ~/repos/docs.blockstack/_data/clarityRef.json
   ```

3. Build the documentation and verify the Clarity reference is building correctly.

4. Make changes in core
5. Build the docker image
6. Run doc gen with the new image

    ```
   $ docker run --name docsbuild -it blockstack-test blockstack-core docgen | jsonpp > ~/repos/docs.blockstack/_data/clarityRef.json
    ```
## To view the clarity cli

You can view [the source code](https://github.com/blockstack/blockstack-core/blob/develop/src/clarity.rs).

1. Pull the Blockstack core clarity-developer-preview image from Docker Hub.

   ```bash
    $ docker pull blockstack/blockstack-core:clarity-developer-preview
   ```

2. Start the Blockstack Core test environment with a Bash shell.

    ```bash
    $ docker run -it -v $HOME/blockstack-dev-data:/data/ blockstack/blockstack-core:clarity-developer-preview bash
    ```

    The command launches a container with the Clarity test environment and opens a bash shell into the container.

3. Run the clarity-cli in the shell.

    ```bash
    root@5b9798633251:/src/blockstack-core# clarity-cli
    Usage: clarity-cli [command]
    where command is one of:

    initialize         to initialize a local VM state database.
    mine_block         to simulated mining a new block.
    get_block_height   to print the simulated block height.
    check              to typecheck a potential contract definition.
    launch             to launch a initialize a new contract in the local state database.
    eval               to evaluate (in read-only mode) a program in a given contract context.
    eval_raw           to typecheck and evaluate an expression without a contract or database context.
    repl               to typecheck and evaluate expressions in a stdin/stdout loop.
    execute            to execute a public function of a defined contract.
    generate_address   to generate a random Stacks public address for testing purposes.
    ```


# Technology Reference

* [UIKit](https://getuikit.com/docs/grid)
* [Liquid templates](https://shopify.github.io/liquid/)