gcanti / gcanti/docs-ts

View rendered docs locally

Open
#40 4 comments 1 reaction 0 assignees View on GitHub
enhancement question
Dominant language
TypeScript
Stars
105
Forks
18
PR merge metrics
No merged PRs in 30d

Description

Currently, we only mention in the README:

"...the generated output of docs-ts can be used as a publishing source for your repository's documentation on GitHub".

## Workable Recipe

Maybe it would be nice to have a way to review the rendered docs locally.

For me the following worked. And as a non-ruby-ist it took me a while to figure out:

1. Put a `Gemfile` with this content into the `docs` folder:
```
source "https://rubygems.org"

gem "github-pages", "~> 212", :group => :jekyll_plugins
```

2. Run `cd docs; bundle exec jekyll serve`

## Include somehow in docs-ts?

Would it make sense to include the Gemfile in the generated output and then add a section to the readme that explains how to run jekyll on it?
Or maybe you have other suggestions here.

## Hot reload

Furthermore, I tried to setup a complete hot reloading workflow, and this worked:

If you run
```
cd docs; bundle exec jekyll serve --livereload
```
and in parallel:
```
while inotifywait -e close_write src; do yarn docs; done
```

The docs are refreshed in the browser on every file save. However, maybe only suitable for small projects, as all the files are processed on each trigger. So this might another topic.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the README and the generated docs output described in the issue, then review the proposed docs/Gemfile using github-pages and the documented `bundle exec jekyll serve` workflow. Done should be a decided, documented way to review rendered docs locally, with the Gemfile included in generated output only if that approach is adopted.

Written by the indexing model from the issue text.

Assessment

Tech stack
ruby, typescript
Domain
documentation
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.