Add the ability to serve the blog locally for review.

[gisraptor]

I have added a quick and easy way to view the blog locally before posting it to the Web. Hopefully this will help with developing themes for Tinkerer, as well as, give us an opportunity to check out posts prior to uploading them. I have added unit tests to verify that the server is pulling posts as expected.

Thank you for your work on Tinkerer. It is great software and I have quite enjoyed hacking on it.

[serra]

This is a good idea.

The alternative I've used thus far is starting a simple http server from the root of the project, where index.html is located. I do that running a batch script (I'm mostly on Windows):

python -m SimpleHTTPServer 8888 &

@gisraptor could you elbaorate on the advantages of this pull request over this one-line script?

BTW, it appears the CI build fails, probably because you don't have permissions on the Travis server to start an http server instance. Please check the "failed" notice on the bottom of your pull request description.

[gisraptor]

@serra Here are a few of the advantages I see coming from this:

• Internalizing the server functionality gives Tinkerer a more civilized reputation polished presentation when compared with other blog hosting software (or at least keeps it on par with others)
• The command to run the server is easier to remember (although the batch/shell script couldn't be that hard)
• It makes testing/developing new themes easier
• Tinkerer ensures that I start the server from the base directory, same as almost everything else
• It can take multiple simultaneous requests due to the use of the ThreadingMixin from the SocketServer module

I took a look at the CI build failed notice on Travis. It appears it failed only in the Python2.6 environment, which I subsequently ran successfully on my local box. The Python2.7 and Python3 environments completed without a problem. I suspect the build box was still spinning up the server when the request for the page was issued and the request was not answered. I have introduced a time delay in the test to mitigate errors of this sort. If it continues I will be glad to look into it further.

Thanks for considering this change.

[vladris]

I don't quite understand why you would want to use an HTTP server to locally preview your blog. Tinkerer generates a static website so you can achieve the same just by opening index.html in your favorite browser. That is how I preview all posts and how I work on themes. Since it's all static, it can be served directly from the local file system. I don't see why you would need an HTTP server. What am I missing here?

[gisraptor]

@vladris I agree that viewing static HTML content works just fine without the HTTP server and it would seem to be overkill. The problem arises when a user would like to include any external Javascript components in their blog. Those components will not be loaded and cannot be previewed to see the full impact of the page, without serving them. Having a simple way to serve the blog locally would allow users the ability to use Javascript in their blogs. It would also allow the use of page scaffolding toolkits for the blog layout such as Bootstrap or HTML5 Boilerplate. Maybe I am trying to expand the initial intent of Tinkerer. If so, I would hope that you would consider my viewpoint. Thanks.

[serra]

I've included some d3js charts with my blog that required serving the blog from behind an http server at design time. So I do see the use case, but I'm not sure if this should be a core feature of tinkerer. For me the one line script from above is sufficient.

[gisraptor]

I would like to understand the motivation for the development of Tinkerer. Would you mind helping me get a better picture of Tinkerer's direction? That will help me understand why this feature may not be desirable and give me some ideas on how to contribute in a more productive fashion. Thanks.

[vladris]

Sure. Tinkerer is meant to be a static blog file generator - think Octopress. The idea is you write your blog in RST format, you build it, and end up with a bunch of html files which you can host on places like BitBucket, GitHub or anywhere else for that matter. RST is great and Sphinx is an awesome tool but it was built for writing documentation not blogging. Tinkerer tries to close that gap by providing a set of extensions and tooling to allow blog building with the Sphinx engine.

Neither Sphinx nor Tinkerer have anything to do with the way you decide to serve the built files.

While I don't deny that it might be useful to quickly spin up a server to locally preview Tinkerer served over HTTP, I don't believe this should be part of the core translating-RST-into-a-blog functionality. You could definitely contribute this as an external tool that can serve the blog, but not part of Tinkerer core. You can either put it on PyPI or pull it to tinkerer-contrib repository, but I'd rather have it as a standalone.

Thanks for your interest in the project and I'm looking forward to seeing your future contributions!

[gisraptor]

@vladris @serra I have been pulling the changes I made out into its own project, using Tinkerer as a template to set things up. Distributing my Python code is new territory for me, so I am learning as I go. I plan to distribute through PyPI and GitHub. The name that I have come up with is Tinkerer-Localpost, since it derives directly from Tinkerer. Before I post it up for the world to see though, I wanted to get your permission to use Tinkerer in the name of the application and I also wanted to know if creating an addon repository for something like this might be better. It doesn't really fall in the category of an extension, as all of the extensions in the tinkerer-contrib repository are Sphinx/Tinkerer content generation extensions. Thanks.

[vladris]

You can use Tinkerer in the name of your application, no worries. You can pull it to tinkerer-contrib if you want. I know right now there are only extensions there, but it doesn't have to be that way. If not, you can definitely go for PyPI. Good luck!

[gisraptor]

Thank you. I think I will give PyPI a try. This is a good exercise for me to go through. I have been a big open source user in the past, but am now trying to give something back and I would like to learn how I can do that most effectively. Thanks for your help and for providing such a great tool.