search

duckduckgo / duckduckhack-docs

DuckDuckHack Instant Answer documentation for developers
http://docs.duckduckhack.com
Other
78 stars 75 forks source link

Use POD documentation for Roles #18

Closed GuiltyDolphin closed 5 years ago

GuiltyDolphin commented 8 years ago

backend-reference/goodie-helpers contains some documentation for the GoodieRoles.

Would it be possible to move this documentation over to POD, directly in the roles (as with WhatIs) then have some HTML generated for this (or other means) that the docs then use?

Would make it easier to keep the documentation in sync, as well as make it a lot easier for developers to view the documentation for the roles locally.

moollaza commented 8 years ago

@GuiltyDolphin we previously discussed doing everything in POD or having a way to include it. For the most part, there's considerably less POD than anything else so we never integrated it.

We've recently switched to using GitBook for our docs, which doesn't seem to support POD.

We could have the docs link to the files though for the purpose of keeping it up to date. If we can render the POD to Markdown, we could paste that output into the docs to manually keep them in sync?

moollaza commented 8 years ago

@talsraviv any thoughts on this?

talsraviv commented 8 years ago

That sounds smart. I don't mind manually updating the docs - that sounds like the normal workflow anyways for everything else, and having POD in the files themselves doesn't hurt, as long as the duplication is one-way.

I thought about linking. I'd prefer to keep all documentation in one place if we can, to make it more accessible to everyone, easy to navigate, and be able to add context when necessary.

Anytime there's new functionality added feel free to make a PR on the docs repo and paste in the new function/description.... or open an issue and I'd be happy to do it.

GuiltyDolphin commented 8 years ago

@talsraviv Hmm... I'm trying to figure this out over on read the docs where I can play around with the source a bit more.

I'll let you know if I come up with anything.

GuiltyDolphin commented 8 years ago

@talsraviv Sphinx/ReST is looking really promising for reducing code-redundancy, it lets you specify text that is repeated throughout several documents and has various other features (such as improved referencing and directives).

It even has a link checker built-in!

I'll play around with it on one of my branches for a while and keep you posted - the read the docs pages will point to that.