[
https://issues.apache.org/jira/browse/CASSANDRA-12533?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15449434#comment-15449434
]
Tyler Hobbs commented on CASSANDRA-12533:
-----------------------------------------
bq. the images committed in tree are broken in the first place (they are all 0
bytes). So if the proper versions are committed, happy to fix the copy part and
regenerate the whole thing with that.
Ah, I must have messed that up when squashing commits into a patch. I've
committed the proper images to trunk as
{{7ea727cded53da6f8faefd88d4131222c1cbd727}}.
bq. For instance, the last update made the doc on the website be the "3.10" one
(even though that's neither released, nor will before more than a month).
I wasn't exactly sure what to do here. Should we just avoid deploying docs
from branches that aren't released yet? If that's the case, what should we do
for tickets like CASSANDRA-12449, which are just general improvements and not
really version-specific? I considered cherry-picking the improvements to a
branch off of the last release tag. The problem there is that I can't push
that branch to the apache repo, and so any later doc improvements for the same
release version would get confusing. I'm sure we can come up with a reasonable
policy for docs, I just don't know what it is yet.
bq. The doc is intrinsically versioned by released (especially now that it's in
tree) while the website isn't. I suspect making the website part of the current
in-tree doc is doable but would be weird and error-prone on that front (to deal
with publishing releases for instance).
That's true.
bq. I'm not pretending this is perfect though, and the integration of the doc
in the website is arguably a tad hacky. But it's not that complex I think, once
you look in detail).
I'm sure that we will get some of the wrinkles ironed out over time, but I do
have to admit that I had a good amount of trouble figuring out the integration,
despite understanding Sphinx pretty well. Perhaps writing out some notes on
what exactly Jekyll does with the current setup would be good.
> Images not handled correctly on website
> ---------------------------------------
>
> Key: CASSANDRA-12533
> URL: https://issues.apache.org/jira/browse/CASSANDRA-12533
> Project: Cassandra
> Issue Type: Bug
> Components: Documentation and Website
> Reporter: Tyler Hobbs
> Assignee: Sylvain Lebresne
>
> In the new [IDE|http://cassandra.apache.org/doc/latest/development/ide.html]
> section of the website, the images are not working. In {{site/public}} in
> SVN, the new images aren't anywhere to be found, so either the build process
> isn't transferring them correctly, or they're being used incorrectly in the
> original Sphinx source.
> On a related note, the styling for the "Hint" section on that page is
> missing. That might be intentional, I'm not sure.
> More generally, I'm curious as to why we're using both Jekyll and Sphinx and
> not just Sphinx alone? It's sort of hard to tell how to fix this issue with
> both tools in use.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
