A few tweaks based on running the docs

[jarednova]

Hey @gchtr I got this running but ran into a few issues. This PR is more for FYI and review than merging (unless you want to try fixing this stuff here, of course)

Made Progress on...

• Added a few things to the .gitignore (I think these based on what I know about Hugo. But it might be necessary to keep these tracked in Git for publishing/deployment reasons)
• In generate-docs.sh it needed a reference/ directory to place the .md files

But I ran into...

This PHP Noitce when I run the script:

The generated MD files also contain that same warning:

Notice: Undefined offset: 0 in /Users/jared/Sites/timber-docs/generator/PHPDocsMD/Reflector.php on line 407

[jarednova]

@gchtr I edited my above comment after reading your entire email and realizing I forgot to use your docs/prepare branch. I still get that offset error though. Once we're able to resolve I can setup the remote location in GitHub pages so the paths all work

[gchtr]

@jarednova

Added a few things to the .gitignore (I think these based on what I know about Hugo. But it might be necessary to keep these tracked in Git for publishing/deployment reasons)

I think it depends on how the docs will be published. Based on Configuring a publishing source for GitHub Pages, the docs folder needs to have data inside it.

Another option would be to use another repository just for the published files.

I don’t know if it’s better to work with a gh-pages branch. That’s why I left the Publish section empty in the Readme.

In generate-docs.sh it needed a reference/ directory to place the .md files

I removed the .gitkeep files that were intended to prevent errors for missing folders and used mkdir commands instead.

The generated MD files also contain that same warning: Notice: Undefined offset: 0 in /Users/jared/Sites/timber-docs/generator/PHPDocsMD/Reflector.php on line 407

I too had the error (written to php_error.log), that’s why I didn’t see it while using the bash script. I guess the output into the MD files depends on how error handling is setup on your machine when running PHP from the command line.

Anyways, should be fixed now.

Relative links in the index.html file — otherwise I got 404s looking for files like http://timber.github.io/css/styles.css. But I also see that Hugo overwrote the TOC with less stuff

I changed the links to use relative instead of absolute URLs. I hope this is easier to handle. I added some more information about how to work with the baseURL to the Readme.

But this also depends on how the docs will be published. The current baseURL is "http://timber.github.io/docs/", because that’s where I suppose the docs will lie when using Github Pages.

[jarednova]

Excellent! The build worked for me that time. I just setup repo to serve stuff on the public end. It's looking good except for the CSS, but I think this PR should resolve it....