3 ms·

Show HN: Create documentation websites from Markdown

4 points by jacec 10y ago

andrewshadura 10y ago
But there's hotdoc: https://github.com/hotdoc/hotdoc https://github.com/hotdoc/hotdoc
- jacec 10y ago
  Took a quick look at hotdoc. Seems like it has a lot of dependencies. (docsgen is just one file) I didn't look into it too much, but it has a very large code base for something that seems fairly simple (from my point of view...) Could you explain why you would choose hotdoc over my tool, does it have some extra features?
  - andrewshadura 10y ago
    Does anyone care about dependencies as long as they're packaged or can be installed automatically? It's a real documentation system rather than just an HTML generator, which is what docsgen seems to be. It supports syntax highlighting, search and DevHelp generation. It maintains a database of symbols and lets you refer to them instead of having to manually look up the link. And there's also an optional component, hotdoc-server, to allow previewing and editing documentation on-line. Well, and it ships with lots of documentation.
    - jacec 10y ago
      Maybe people dont care about dependencies, i do so i decided to use Go to make a single file. Because of the dependencies it seems like HotDoc only works on a server? Docsgen has versions for Windows, Mac and Linux without the need to have a server, virtual machine or stuff like that. This is just the start of docsgen. I have planned code comment parsing, versioning, multi language support and more stuff. Syntax highlighting is almost finished for docsgen as well. What i'm trying to build is a really lightweight solution that everyone can use without having to setup a lot of things. Docsgen will have a focus on API documentation rather then library documentation which HotDoc seems to focus.
      - andrewshadura 10y ago
        I'm not sure why are you making distinction between library documentation and API documentation, especially so considering that hotdoc's GitHub repository says: ‘HotDoc: the tastiest API documentation system’.
      - andrewshadura 10y ago
        Also, why are you saying hotdoc works "on a server" only? What's "a server" in your understanding? By the way, hotdoc works on any platform where Python runs. In particular, once you've got Python running, pip install hotdoc installs it for you even if you don't have packages for your distribution.
        jacec 10y ago
        I was simply asking if it only works on a server. I was reading the installation guide and it has command line installs for Fedora and Ubuntu so i thought it was only for servers. Will pip also install the system-wide dependencies? As for API documentation vs Library documentation it just seems like HotDoc is for Library documentation. (Even though it's the tastiest API documentation system) From their examples they are just showing Library documentation sites? Docsgen is inspired by API docs like DO and PayPal where you have text on left and example request and response on the right. Example: https://developers.digitalocean.com/documentation/v2/ https://developers.digitalocean.com/documentation/v2/ I have trouble finding examples of API documentation sites that uses HotDoc, feel free to link some and i will check them.
        andrewshadura 10y ago
        Sure, pip installs either system-wide dependencies or, if you as it, installs them into your home. As for API, I now see what you mean, you use the term API is a different meaning than I do (remote API vs local API), hence the misunderstaning. No, I don't think hotdoc supports side-by-side documentation and examples at the moment. I think it can be extended to do so, though.

4 points by jacec 10y ago

andrewshadura 10y ago

But there's hotdoc: https://github.com/hotdoc/hotdoc https://github.com/hotdoc/hotdoc

jacec 10y ago
Took a quick look at hotdoc. Seems like it has a lot of dependencies. (docsgen is just one file) I didn't look into it too much, but it has a very large code base for something that seems fairly simple (from my point of view...) Could you explain why you would choose hotdoc over my tool, does it have some extra features?
- andrewshadura 10y ago
  Does anyone care about dependencies as long as they're packaged or can be installed automatically? It's a real documentation system rather than just an HTML generator, which is what docsgen seems to be. It supports syntax highlighting, search and DevHelp generation. It maintains a database of symbols and lets you refer to them instead of having to manually look up the link. And there's also an optional component, hotdoc-server, to allow previewing and editing documentation on-line. Well, and it ships with lots of documentation.
  - jacec 10y ago
    Maybe people dont care about dependencies, i do so i decided to use Go to make a single file. Because of the dependencies it seems like HotDoc only works on a server? Docsgen has versions for Windows, Mac and Linux without the need to have a server, virtual machine or stuff like that. This is just the start of docsgen. I have planned code comment parsing, versioning, multi language support and more stuff. Syntax highlighting is almost finished for docsgen as well. What i'm trying to build is a really lightweight solution that everyone can use without having to setup a lot of things. Docsgen will have a focus on API documentation rather then library documentation which HotDoc seems to focus.
    - andrewshadura 10y ago
      I'm not sure why are you making distinction between library documentation and API documentation, especially so considering that hotdoc's GitHub repository says: ‘HotDoc: the tastiest API documentation system’.
    - andrewshadura 10y ago
      Also, why are you saying hotdoc works "on a server" only? What's "a server" in your understanding? By the way, hotdoc works on any platform where Python runs. In particular, once you've got Python running, pip install hotdoc installs it for you even if you don't have packages for your distribution.
      - jacec 10y ago
        I was simply asking if it only works on a server. I was reading the installation guide and it has command line installs for Fedora and Ubuntu so i thought it was only for servers. Will pip also install the system-wide dependencies? As for API documentation vs Library documentation it just seems like HotDoc is for Library documentation. (Even though it's the tastiest API documentation system) From their examples they are just showing Library documentation sites? Docsgen is inspired by API docs like DO and PayPal where you have text on left and example request and response on the right. Example: https://developers.digitalocean.com/documentation/v2/ https://developers.digitalocean.com/documentation/v2/ I have trouble finding examples of API documentation sites that uses HotDoc, feel free to link some and i will check them.
        andrewshadura 10y ago
        Sure, pip installs either system-wide dependencies or, if you as it, installs them into your home. As for API, I now see what you mean, you use the term API is a different meaning than I do (remote API vs local API), hence the misunderstaning. No, I don't think hotdoc supports side-by-side documentation and examples at the moment. I think it can be extended to do so, though.