It would probably be more productive to list some specific concerns you have
with Hugo. Then explain why you think they make using it a bad idea. Then offer
some alternatives.
On 3/16/18, 1:18 PM, "Kenneth Brotman" <kenbrot...@yahoo.com.INVALID> wrote:
Thanks for that Eric Evans.
I'm not sure Hugo is the way to go. I don't see how I would generate the
quality of work I would want with it. It seems like another example of coders
learning and using a more complicated program to generate the code they could
have already generated - it’s a disease in the I.T. industry right now. But I
could be wrong.
Here's the thing. I've been spending a lot of my time for the past three
weeks now trying to help with the website. That is a tiny website. I've never
worked with a website that tiny. Bear with me.
I'm studying Jeff Carpenter and Eben Hewitt's book: Cassandra The
Definitive Guide
https://www.amazon.com/Cassandra-Definitive-Guide-Distributed-Scale/dp/1491933666/ref=sr_1_1?ie=UTF8&qid=1521230539&sr=8-1&keywords=cassandra+the+definitive+guide
and have already have a terrible itch to start contributing some code. I just
want to get set up to do that. The book seems to be a good way to get familiar
with the internals and the code of Cassandra.
I can only do so much for the group at one time just like anyone else.
I'll only do top quality work. I'll only be a part of top quality work. It
could be that I won't feel comfortable with what the group wants to do for the
website.
Please keep working on it as it is really embarrassing, terrible,
substandard unacceptable beneath professional standards...
I will contribute if it's possible for me to do so. Let's see what we
decide to do going forward for the website.
Kenneth Brotman
(Cassandra coder?)
-----Original Message-----
From: Eric Evans [mailto:john.eric.ev...@gmail.com]
Sent: Friday, March 16, 2018 7:59 AM
To: dev@cassandra.apache.org
Subject: Re: A JIRA proposing a seperate repository for the online
documentation
On Thu, Mar 15, 2018 at 11:40 AM, Kenneth Brotman
<kenbrot...@yahoo.com.invalid> wrote:
> Well pickle my cucumbers Jon! It's good to know that you have experience
with Hugo, see it as a good fit and that all has been well. I look forward to
the jira epic!
>
> How exactly does the group make such a decision: Call for final
discussion? Call for vote? Wait for the PMC to vote?
Good question!
Decisions like this are made by consensus; As the person who is attempting
to do something, you discuss your ideas with the group, listen to the feedback
of others, and develop consensus around a direction.
This is more difficult than demanding your way, or having someone(s) in a
position of absolute power tell you what you can and cannot do, but the result
is better.
> -----Original Message-----
> From: Jon Haddad [mailto:jonathan.had...@gmail.com] On Behalf Of Jon
> Haddad
> Sent: Thursday, March 15, 2018 9:24 AM
> To: dev@cassandra.apache.org
> Subject: Re: A JIRA proposing a seperate repository for the online
> documentation
>
> Murukesh is correct on a very useable, pretty standard process of
multi-versioned docs.
>
> I’ll put my thoughts in a JIRA epic tonight. I’ll be a multi-phase
process. Also correct in that I’d like us to move to Hugo for the site, I’d
like us to have a unified system between the site & the docs, and hugo has been
excellent. We run the reaper site & docs off hugo, it works well. We just
don’t do multi-versions (because we don’t support multiple):
https://github.com/thelastpickle/cassandra-reaper/tree/master/src/docs
<https://github.com/thelastpickle/cassandra-reaper/tree/master/src/docs>.
>
> Jon
>
>> On Mar 15, 2018, at 8:57 AM, Murukesh Mohanan
<murukesh.moha...@gmail.com> wrote:
>>
>> On Fri, Mar 16, 2018 at 0:19 Kenneth Brotman
>> <kenbrot...@yahoo.com.invalid <mailto:kenbrot...@yahoo.com.invalid>>
>> wrote:
>>
>>> Help me out here. I could have had a website with support for more
>>> than one version done several different ways by now.
>>>
>>> A website with several versions of documentation is going to have
>>> sub-directories for each version of documentation obviously. I've
>>> offered to create those sub-directories under the "doc" folder of
>>> the current repository; and I've offered to move the online
>>> documentation to a separate repository and have the sub-directories
>>> there. Both were shot down. Is there a third way? If so please just
spill the beans.
>>>
>>
>> There is. Note that the website is an independent repository. So to
>> host docs for multiple versions, only the website's repository (or
>> rather, the final built contents) needs multiple directories. You can
>> just checkout each branch or tag, generate the docs, make a directory
>> for that branch or tag in the website repo, and copy the generated
>> docs there with appropriate modifications.
>>
>> I do this on a smaller scale using GitHub Pages (repo:
>> https://github.com/murukeshm/cassandra
<https://github.com/murukeshm/cassandra> site:
>> https://murukeshm.github.io/cassandra/
>> <https://murukeshm.github.io/cassandra/>
>> <https://murukeshm.github.io/cassandra/3.11.1/
>> <https://murukeshm.github.io/cassandra/3.11.1/>> ). The method is a
>> bit hacky as I noted in CASSANDRA-13907. A daily cronjobs updated the
repo if docs are updated. 3.9+ versions are available.
>>
>>
>>
>>
>>> Also, no offense to anyone at Sphinx but for a project our size it's
>>> not suitable. We need to move off it now. It's a problem.
>>>
>>> Can we go past this and on to the documenting! Please help resolve
this.
>>>
>>> How are we going to:
>>> Make the submission of code changes include required changes to
>>> documentation including the online documentation?
>>> Allow, encourage the online documentation to publish multiple
>>> versions of documentation concurrently including all officially
supported versions?
>>
>>
>> Only on this point: we'll need to start by improving the website
>> build process. Michael's comment on 13907 (
>> https://issues.apache.org/jira/browse/CASSANDRA-13907?focusedCommentI
>> d
>> =16211365&page=com.atlassian.jira.plugin.system.issuetabpanels:commen
>> t
>> -tabpanel#comment-16211365
>> <https://issues.apache.org/jira/browse/CASSANDRA-13907?focusedComment
>> I
>> d=16211365&page=com.atlassian.jira.plugin.system.issuetabpanels:comme
>> n
>> t-tabpanel#comment-16211365>
>> )
>> shows it's a painful, fiddly process. That seems to be the main
>> blocker. I think Jon has shown interest in moving to Hugo from the
>> current Jekyll setup.
>>
>>
>>
>>> Move our project onto a more suitable program than Sphinx for our needs?
>>>
>>> Kenneth Brotman
>>>
>>> -----Original Message-----
>>> From: Eric Evans [mailto:john.eric.ev...@gmail.com]
>>> Sent: Thursday, March 15, 2018 7:50 AM
>>> To: dev@cassandra.apache.org
>>> Subject: Re: A JIRA proposing a seperate repository for the online
>>> documentation
>>>
>>> On Thu, Mar 15, 2018 at 4:58 AM, Rahul Singh
>>> <rahul.xavier.si...@gmail.com>
>>> wrote:
>>>>
>>>> I don’t understand why it’s so complicated. In tree docs are as
>>>> good as
>>> any. All the old docs are there in the version control system.
>>>>
>>>> All we need to is a) generate docs for old versions b) improve user
>>> experience on the site by having it clearly laid out what is latest
>>> vs. old docs and c) have some semblance of a search maybe using
>>> something like Algolia or whatever.
>>>
>>> This.
>>>
>>> Keeping the docs in-tree is a huge win, because they can move in
>>> lock-step with changes occurring in that branch/version. I don't
>>> think we've been enforcing this, but code-changes that alter
>>> documented behavior should be accompanied by corresponding changes to
the documentation, or be rejected.
>>> Code-changes that correspond with undocumented behavior are an
>>> opportunity to include some docs (not grounds to reject a
>>> code-review IMO, but certainly an opportunity to politely ask/suggest).
>>>
>>> Publishing more than one version (as generated from the respective
>>> branches/tags), is a solvable problem.
>>>
>>>>> On Thu, Mar 15, 2018 at 1:22 Kenneth Brotman
>>>>> <kenbrot...@yahoo.com.invalid
>>>>> wrote:
>>>>>
>>>>>> https://issues.apache.org/jira/browse/CASSANDRA-14313
>>>>>>
>>>>>>
>>>>>>
>>>>>> For some reason I'm told by many committers that we should not
>>>>>> have sets of documentation for other versions than the current
>>>>>> version in a tree for that version. This has made it difficult,
>>>>>> maybe impossible to have documentation for all the supported
>>>>>> versions on the website at one time.
>>>>>>
>>>>>>
>>>>>>
>>>>>> As a solution I propose that we maintain the online documentation
>>>>>> in a separate repository that is managed as the current
>>>>>> repository under the guidance of the Apache Cassandra PMC
>>>>>> (Project Management Committee); and that in the new repository . . .
>>>>>>
>>>>>>
>>>>>>
>>>>>> Please see the jira. I hope it's a good answer to everyone.
>>>
>>> --
>>> Eric Evans
>>> john.eric.ev...@gmail.com
>>>
>>> --------------------------------------------------------------------
>>> - To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org
>>> For additional commands, e-mail: dev-h...@cassandra.apache.org
>>>
>>>
>>> --------------------------------------------------------------------
>>> - To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org
>>> For additional commands, e-mail: dev-h...@cassandra.apache.org
>>>
>>> --
>>
>> Murukesh Mohanan,
>> Yahoo! Japan
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org
> For additional commands, e-mail: dev-h...@cassandra.apache.org
>
--
Eric Evans
john.eric.ev...@gmail.com
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org
For additional commands, e-mail: dev-h...@cassandra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org
For additional commands, e-mail: dev-h...@cassandra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org
For additional commands, e-mail: dev-h...@cassandra.apache.org
