[
https://issues.apache.org/jira/browse/SOLR-15556?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17486158#comment-17486158
]
Houston Putman commented on SOLR-15556:
---------------------------------------
{quote}And agree it would be a big win if the build could be smart wrt
re-building the guide. But that is maybe hard, as it needs to check out
multiple branches to build every pervious version - and Gradle cannot know
whether there have been changes to those other branches 5 minutes ago?
{quote}
So local builds are only going to build the guide for their branch, not all
other branches. The entire ref-guide build will only really need to be done on
jenkins... except for some changes that won't happen very often. You can still
do it on your own machine (just pass {{{}-PrefGuide.local=false{}}}, but the
default is to use the local one-branch ref-guide.
{quote}Will the entire ref-guide build be part of {{gradlew check -x tests}}
going forward, or can we validate/lint the current guide only withuot a
full-blown html build?
{quote}
Yes, but it's really fast. the link checking takes like 5 seconds and the site
generation takes 18-30 seconds. And I have the caching working now, so if you
don't update anything then you are fine. There is an option to do validation of
xref: links without building the whole guide, but honestly it doesn't save a
whole lot of time and it doesn't let us validate Solr and Lucene javadocs
links. So IMO it's best just to do the whole-site link checking that finds all
of the issues, and live with an extra 10-15 seconds of build time whenever you
make a change.
{quote}It's awesome to see so much progress on this one. Can't wait for it to
be merged!
{quote}
Honestly I think we are very close. Once we get the new page links working (we
can even comment them out in the first place just to get the gradle check
passing), and get rid of the jekyll stuff, we should be good to go I think. One
last thing to look at is being able to customize the UI bundle. I will probably
try to tackle that tomorrow, but that is something that we don't even really
need that badly in the first pass.
> Ref Guide Redesign Phase 3: Replace Jekyll
> ------------------------------------------
>
> Key: SOLR-15556
> URL: https://issues.apache.org/jira/browse/SOLR-15556
> Project: Solr
> Issue Type: Improvement
> Components: documentation
> Reporter: Cassandra Targett
> Assignee: Cassandra Targett
> Priority: Blocker
> Fix For: 9.0
>
>
> The final step of my grand vision for redesigning the Ref Guide is to look at
> replacing Jekyll with a different static site generator.
> The primary reason why is because Jekyll is designed for blog posts, not for
> sites with hundreds of static pages like ours. Back in 2017 when I chose it,
> it was relatively straightforward to implement, a lot of information was
> available in Jekyll docs and the internet in general to customize it, and it
> was one of the few that supported Asciidoc format.
> However now there are a lot more options, including some which are
> specifically designed for large multi-version documentation sites like the
> Ref Guide.
> Included with this will be reorganizing the on-disk organization of the ref
> guide files themselves.
--
This message was sent by Atlassian Jira
(v8.20.1#820001)
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscr...@solr.apache.org
For additional commands, e-mail: issues-h...@solr.apache.org
