# MetacatUI Documentation
This folder of the MetacatUI repository contains the documentation for MetacatUI. This documentation includes:
- Basic information about MetacatUI
- Installation instructions
- Developer documentation for the MetacatUI application


## Building Developer documentation
MetacatUI uses [JSDoc](https://github.com/jsdoc/jsdoc) comments to provide inline documentation of classes, methods, and variables. A JSDoc documentation generator will collect all those comments and generate HTML webpages for easier reading and navigation.

The MetacatUI git repository already contains these generated HTML pages in the `docs/docs` directory. However, if you have made changes to the MetacatUI code and documentation and want to update the HTML doc pages, you will need to run the JSDoc generator.

To build a fresh version of the MetacatUI developer docs, ensure you have [Node](https://nodejs.org/) installed and, from the top level of the repository, install JSDoc and other dependencies with:

```
npm install
```

and then, to build the documentation, run:

```
npm run jsdoc
```

If you're still running the `bundle exec jekyll serve` command described below, your updated documentation will be automatically available at http://localhost:4000/docs/.

Once your changes to the JSDocs are merged into the `main` branch, they will go live on the Github pages site at https://nceas.github.io/metacatui/docs/index.html.

## Building the entire documentation website

This directory is also built into a simple HTML website, using Jekyll, that is hosted on Github Pages. You can view the last published version of the Github site here: https://nceas.github.io/metacatui/

To build a local version of the MetacatUI Github pages site, ensure you have a relatively recent 2.x release of [Ruby](https://www.ruby-lang.org/) (e.g., 2.7.2) installed. (If you are running a 3.x version of Ruby, see "A note on Ruby versions", below.) Then make sure [Bundler](https://bundler.io/) is installed:

```
gem install bundler
```

Install the gems required to build the site with:

```
bundle install
```

Then serve the Jekyll site from the `docs` directory:

```
bundle exec jekyll serve
```

You can now access the MetacatUI documentation website at the localhost address shown by Jekyll (most likely localhost:4000). Jekyll will watch for changes and rebuild the site as you edit the content. NOTE: Changes to the website config in `_.config.yml` will NOT trigger a rebuild, so you will need to stop Jekyll and restart with `bundle exec jekyll serve` again.

[See the Github Pages documentation for additional help](https://help.github.com/en/enterprise/2.14/user/articles/setting-up-your-github-pages-site-locally-with-jekyll#step-4-build-your-local-jekyll-site)


### A note on Ruby versions

If you get an error when you run `bundle exec jekyll serve`, check which version of Ruby you are running:

```
ruby -v
```

If you have 3.x release of Ruby installed, you need to switch to a 2.x version. To switch versions, use `rbenv`:

1. Follow the all the [installation and setup instructions](https://github.com/rbenv/rbenv#installation).
2. Run `brew upgrade rbenv ruby-build`
3. Run `rbenv install 2.x.x` where `2.x.x` is the version (use `rbenv install --list` to see which ones are available) - e.g. `2.7.2`
4. Run `rbenv global x.x.x` to change your global Ruby version

Check that the ruby version was successfully changed to a 2.x version using `ruby -v`. (If not, read some solutions [here](https://stackoverflow.com/questions/10940736/rbenv-not-changing-ruby-version))

Try running `bundle install` then `bundle exec jekyll serve` again.

## Adding to this site
Feel free to add pages to the MetacatUI docs website by adding markdown files to this `docs` directory. Use subdirectories
as much as possible to keep things organized. Use relative links with `.html` suffixes instead of `.md` so that the links work on the Github Pages site.

## Anything missing?
We maintain a list of questions about MetacatUI that are reviewed and worked into this documentation. If you have a question that was not answered by these docs, or want to make a suggestion for these docs, please add to the list by commenting on [the FAQ Github issue](https://github.com/NCEAS/metacatui/issues/1389)