Gearman docs do not display on website

[BasBastian]

Gearman project documentation

which is too poor and inconsistent to talk about. I do not indend to offend you, the people, who keep maintaining this project (though previous statement might sound insulting). Confusing, in fact, is the way gearman is documented: gearman.org and gearman.info pages.

Those two mentioned sources are complementary for each other sometimes. I know where gearman.github.io is redirecting me (gearman.org) but I am not sure if I should trust that page, because it looks like incomplete and buggy (for example: I cannot see docs/dev directory).

I am well aware that it is not an easy task - especially for @SpamapS who recently got involved in maintenence of this (abandoned by God :) ) project. But even if I'd like to help, it must be clear what is the most recent documentation version and how to contribute.

Are you able to provide such information? Should I just install python-sphinx (another thing not documented) and develop sources in docs/ directory, or alter sources of another repository (like https://github.com/gearman/gearman.github.io).

It is not clear and I'd like it to be cleared.

[SpamapS]

WELCOME! Thanks so much for your interest in helping out. Indeed, I have near 0 time for any sustained contribution to the project. It's all I can do to keep up with basic code maintenance and bug triage.

Today is the first day I heard about gearman.info. @BrianAker I assume this is your domain and you can perhaps make it redirect to a page on gearman.org once we get that building and displaying the sphinx docs.

As far as the sphinx docs, we'll need a travis job or something similar to go ahead and publish sphinx docs into a branch of gearman.github.io so we can publish it there. I would welcome your contribution to set that build job up.

[BrianAker]

By God you say? Should I ask which? :) Sorry for the confusion, the history of this is that gearman.org was not available for… some period of time so I used gearman.info. There was also a SEO available at the time that made some sense (I believe, this was a long time ago). — Brian

On Oct 24, 2017, at 11:03 AM, BasBastian ***@***.***> wrote: Gearman project documentation which is too poor and inconsistent to talk about. I do not indend to offend you, the people, who keep maintaining this project (though previous statement might sound insulting). Confusing, in fact, is the way gearman is documented: gearman.org and gearman.info pages. Those two mentioned sources are complementary for each other sometimes. I know where gearman.github.io is redirecting me (gearman.org) but I am not sure if I should trust that page, because it looks like incomplete and buggy (for example: I cannot see docs/dev directory). I am well aware that it is not an easy task - especially for @SpamapS <https://github.com/spamaps> who recently got involved in maintenence of this (abandoned by God :) ) project. But even if I'd like to help, it must be clear what is the most recent documentation version and how to contribute. Are you able to provide such information? Should I just install python-sphinx (another thing not documented) and develop sources in docs/ directory, or alter sources of another repository (like https://github.com/gearman/gearman.github.io <https://github.com/gearman/gearman.github.io>). It is not clear and I'd like it to be cleared. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#141>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAAh3_SWpPMpliX1JL_SmiN7cTOSrTWoks5sviaMgaJpZM4QE2gv>.

乌

[BrianAker]

Something to think about… Gearman has multiple implementations. I have always had an ethics dilemma around making a definitive statement around “which version is clearly the reference implementation”. One of the reasons I kept the Gearman.info site with just the C implementation was to keep a small wall up in order to keep clean hands about this. I am not sure if this matters as much today as it did several years ago. None of the other implementations, with the exception of the original, were maintained for long periods of time. One or two clearly did not implement the protocol correctly as well.

On Oct 24, 2017, at 1:26 PM, Clint Byrum ***@***.***> wrote: WELCOME! Thanks so much for your interest in helping out. Indeed, I have near 0 time for any sustained contribution to the project. It's all I can do to keep up with basic code maintenance and bug triage. Today is the first day I heard about gearman.info. @BrianAker <https://github.com/brianaker> I assume this is your domain and you can perhaps make it redirect to a page on gearman.org once we get that building and displaying the sphinx docs. As far as the sphinx docs, we'll need a travis job or something similar to go ahead and publish sphinx docs into a branch of gearman.github.io so we can publish it there. I would welcome your contribution to set that build job up. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#141 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAAh32JfVddVM-JjzT_7mo8ZG_kt4totks5svkgGgaJpZM4QE2gv>.

乌

[BasBastian]

@BrianAker . I am asking because in project's directory /docs there is a Makefile that uses sphinx and build documentation. Is it still up to date and we should reuse that behavior or we should refrain from using those and remove that directory from project?

Maybe that should be the place where developers tell others about gory details on project. Or maybe we should "keep calm and use Jekyll" for developer's documentation as well ?

I mean those sources: https://github.com/gearman/gearman.github.io
Because Jekyll is only blogging-like page generator. It does not analyze source code, only reads reStructured Text files and generates web page out of them (almost the same as Jekyll).

Maybe there should be a place for a tool like Doxygen? Or maybe Jekyll should use some other utility to read comments out of source code.

[BrianAker]

I am not a fan of Doxygen. I can explain why if you want. If you are asking for a suggestion, I would just build the Sphinx pages offline and publish them. Technically that is what is still happening today, only the jobs are pointed at launchpad (aka the BZR repositories). Adjusting that to git/etc is not worth the trouble. I prefer Sphinx, Jekyll has no structure for code (that I am aware of). You can suppress Jekyll via: https://github.com/blog/572-bypassing-jekyll-on-github-pages Right now the documentation builds very accurate man pages, which cross-reference. This is expressed in the html that is generated as well. 乌

…

On Oct 25, 2017, at 10:59, BasBastian ***@***.***> wrote: @BrianAker . I am asking because in project's directory /docs there is a Makefile that uses sphinx and build documentation. Is it still up to date and we should reuse that behavior or we should refrain from using those and remove that directory from project? Maybe that should be the place where developers tell others about gory details on project. Or maybe we should "keep calm and use Jekyll" for developer's documentation as well ? I mean those sources: https://github.com/gearman/gearman.github.io Because Jekyll is only blogging-like page generator. It does not analyze source code, only reads reStructured Text files and generates web page out of them (almost the same as Jekyll). Maybe there should be a place for a tool like Doxygen? Or maybe Jekyll should use some other utility to read comments out of source code. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[BasBastian]

Great. Thanks for an answer.

Building pages offline is not the best option in my opinion (maybe we should change channel of discussing details to IRC or groups.google.com) and I would like to hear your arguments against Doxygen.

Not to prolong the stage of choosing of the right tool I will try to bypass Jekyll (I read about it already but thanks for mentioning it) and run Travis job that would build documentation configured in Sphinx.

To make things clear - I already know how documentation pages are built in docs/ directory (the basics - truth to be told). Thanks for your opinion on Jekyll vs. Sphinx dillema.

[BasBastian]

Something might have gone wrong and not done:

Probably stylesheets have bad location after performing mv.

[BasBastian]

Pull Request was created few minutes ago. Please check if those small changes would not disrupt the overall flow of building app and would not affect gearman.org page.

@SpamapS - you'd be the most experienced in that matter, probably. Please generate Github API token and provide GITHUB_TOKEN variable (same as generated token) in gearman/gearmand repository's related TravisCI account (or maybe @BrianAker would be more apropriate person to ask).