search

gcanti / docs-ts

A zero-config documentation tool for my TypeScript projects
https://gcanti.github.io/docs-ts/
MIT License
101 stars 17 forks source link

View rendered docs locally #40

Open m-bock opened 3 years ago

m-bock commented 3 years ago

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.
IMax153 commented 3 years ago

While I think this is potentially useful, I think it is outside the scope of the library.

I think the biggest issue for me here is the work that is required on behalf of the library user to get this up and running. If we could figure out a more user-friendly way to allow users to visualize their documentation (maybe via a Docker image that we bundle with the lib or something), then I would be all for this.

gillchristian commented 3 years ago

We could add the instructions to the docs on how to run locally with Jekyll.

However, if we include something I'd rather go the Dockerfile way as well.

IMax153 commented 3 years ago

That is very true - I do think this could be super useful to someone trying to figure out what the rendered docs would look like, especially with other themes.

@thought2 - maybe you could open a PR to add the instructions for doing this to the FAQ section in the README?

m-bock commented 3 years ago

I'm about to create a PR with a docker file. I think that really makes sense. There will be some instructions in the readme, too.

When I have something up and running, we can discuss the details. stay tuned.