[
https://issues.apache.org/jira/browse/CASSANDRA-12533?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15446045#comment-15446045
]
Sylvain Lebresne commented on CASSANDRA-12533:
----------------------------------------------
bq. either the build process isn't transferring them correctly
Yes, it doesn't (for the curious, Sphinx copies images in a {{_images}}
directory on generation but directories starting with an underscore are skipped
by Jekyll). And that's pretty easy to fix (we can force inclusion by Jekyll of
all directories with that name), but at the same time, and as far as I can
tell, the images committed in tree are broken in the first place ([they are all
0
bytes|https://github.com/apache/cassandra/blob/trunk/doc/source/development/images/eclipse_debug0.png]).
So if the proper versions are committed, happy to fix the copy part and
regenerate the whole thing with that.
Btw, the documentation is versioned, so one has to be careful which branch is
checkout when building the doc for the website. 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). Not a bit deal, and I can easily
fix that as well, but mentioning it for the future.
bq. On a related note, the styling for the "Hint" section on that page is
missing. That might be intentional, I'm not sure.
It's not, I'll fix that with the rest once I have the proper images.
bq. I'm curious as to why we're using both Jekyll and Sphinx and not just
Sphinx alone?
First, because I honestly just didn't considered putting it all in the Sphinx
doc (I looked at updating the website somewhat independently of the doc, which
I didn't really originally plan to "integrate" tightly, so Sphinx didn't come
in mind). But now that you mention it, I think the arguments for that choice
would be:
* Sphinx is a documentation tool and while I know that Sphinx can include
"static" content, I'd be slightly wary of abusing the tool for something it's
not built for (as most fear, that one might be unfounded though).
* I think we'll ultimately want multiple versions of the doc for just one
website. 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).
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).
> 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)
