Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

nightly sphinx docs? #31

Closed
timmie opened this Issue · 4 comments

2 participants

@timmie

Many python projects but also others use Sphinx for documentation.

Could this software be used to also update docs on nightly basis?

Docs are a integral part of software project websites.

@plusjade
Owner

@timmie many people have pointed me toward the awesomeness of sphinx for inspiration. I plan to take a serious look into sphinx after I release ruhoh 1.0.0

As of now I understand sphinx to parse a codebase, extract comments, documentation etc, and output a website. Is this the primary use case, or do users typically build blogs, websites from sphinx?

Could this software be used to also update docs on nightly basis?

Can you walk me through a specific use case? Do you wish to point ruhoh to a codebase and output a doc website? Do you want ruhoh <-> sphinx integration? I ask primarily because I am unfamiliar with the sphinx concepts at the moment.

Docs are a integral part of software project websites.

I'll take that even one step further and say I prefer conceptual based documentation in addition to in-line code documentation. In other words most projects give you the what (what this method does) but not how the application works. Sure you can say "the code explains how" but if you want user adoption, it would be really helpful to read a paragraph about the application flow, main components and their philosophies etc.

@timmie

As of now I understand sphinx to parse a codebase, extract comments, documentation etc, and output a website.
this is the case.

code:
https://github.com/pydata/pandas/tree/master/doc/source

website:
http://pandas.pydata.org/pandas-docs/stable/index.html

But more to that, it can use docstrings in such to build API and function, lcass docs automatically.

Can you walk me through a specific use case? Do you wish to point ruhoh to a codebase and output a doc website?
Yes.
A developer commits a fix in a docstring or documentation directory. Then, a program coudl sense this change and runs a Sphinx build to update that statics section of a website.

@timmie

As of now I understand sphinx to parse a codebase, extract comments, documentation etc, and output a website.
this is the case.

code:
https://github.com/pydata/pandas/tree/master/doc/source

website:
http://pandas.pydata.org/pandas-docs/stable/index.html

But more to that, it can use docstrings in such to build API and function, lcass docs automatically.

Can you walk me through a specific use case? Do you wish to point ruhoh to a codebase and output a doc website?
Yes.
A developer commits a fix in a docstring or documentation directory. Then, a program coudl sense this change and runs a Sphinx build to update that statics section of a website.

@plusjade
Owner

Sphinx support is outside the scope of ruhoh as publishing software at least in the immediate feature, but these are good ideas in philosophy.

@plusjade plusjade closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.