Skip to content

Commit

Permalink
added README to docs and updated CHANGELOG
Browse files Browse the repository at this point in the history
  • Loading branch information
bgunnar5 committed Jan 22, 2024
1 parent fce2989 commit 51f9796
Show file tree
Hide file tree
Showing 2 changed files with 46 additions and 0 deletions.
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Added tables for all command options
- Added examples for commands that have multiple options
- Added more links to places in the documentation so that it's easier for users to find info they're looking for
- New "Running Studies" page to explain different ways to run studies, restart them, and accomplish command line substitution
- New "Interpreting Output" page to help users understand how the output workspace is generated in more detail
- New "Examples" page has been added
- The goal is to have a detailed explanation of each example
- For now, the only example that's completed here is the "Hello, World!" example
Expand Down
44 changes: 44 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Guide to Merlin Documentation

Merlin uses [MkDocs](https://www.mkdocs.org/) to generate its documentation and [Read the Docs](https://about.readthedocs.com/?ref=readthedocs.com) to host it. This README will detail important information on handling the documentation.

## How to Build the Documentation

Ensure you're at the root of the Merlin repository:

```bash
cd /path/to/merlin/
```

Install the documentation with:

```bash
pip install -r docs/requirements.txt
```

Build the documentation with:

```bash
mkdocs serve
```

Once up and running, MkDocs should provide a message telling you where your browser is connected (this is typically `http://127.0.0.1:8000/`). If you're using VSCode, you should be able to `ctrl+click` on the address to open the browser window. An example is shown below:

```bash
(venv_name) [user@machine:merlin]$ mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
WARNING - Excluding 'README.md' from the site because it conflicts with 'index.md'.
WARNING - A relative path to 'api_reference/' is included in the 'nav' configuration, which is not found in the documentation files.
INFO - Documentation built in 3.24 seconds
INFO - [09:16:00] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO - [09:16:00] Serving on http://127.0.0.1:8000/
```

## Configuring the Documentation

MkDocs relies on an `mkdocs.yml` file for almost everything to do with configuration. See [their Configuration documentation](https://www.mkdocs.org/user-guide/configuration/) for more information.

## How Do API Docs Work?

Coming soon...

0 comments on commit 51f9796

Please sign in to comment.