Improvements for book sources #1250
Conversation
This adds two features that are sort of interlinked in their
implementation but not so much in their use. We want them both though, I
think:
1. Allows books to explictly depend on files in the docs repo so they
are rebuilt when those files are changed.
2. Create attributes for the "root" of each repository. This should make
a lot of the `../../../../` paths unneeded.
So the second feature allows you to write includes like:
```
include::{elasticsearch-root}/docs/reference/glossary.asciidoc[]
```
instead of:
```
include::{docdir}/../../../../elasticsearch/docs/reference/glossary.asciidoc[]
```
The first feature combined with the second feature lets you write this
to include the shared files:
```
include::{docs-root}/shared/versions/stack/{source_branch}.asciidoc[]
include::{docs-root}/shared/attributes.asciidoc[]
```
instead of:
```
include::{asciidoc-dir}/../../shared/versions/stack/{source_branch}.asciidoc[]
include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
```
Which is nice. In addition, the first feature lets you write:
```
-
repo: docs
path: shared/attributes.asciidoc
-
repo: docs
path: shared/versions/stack/{version}.asciidoc
```
in `conf.yaml` to cause a book to be rebuilt if either:
* `attributes.asciidoc` changes
* `shared/versions/stack/master.asciidoc` changes. Assuming we're
building the master branch of the book. It'll be `7.x.asciidoc` if we're
building `7.x`, etc.
You can also declare a dependency on
`shared/versions/stack/current.asciidoc` and we'll cause a rebuild if
either `current.asciidoc` changes to point to a new file *or* the file
that it points to changes.
|
@olksdr, I'm going to try and work through the last NOCOMMITs this afternoon. But I figure because this one is all OO-perl you're the best reviewer we have for it. There is a fair bit of ruby too but I think it is pretty uncontroversial stuff. |
|
The error is real. I'll get to it in the morning. Instead of checking the NOCOMMIT I did #1252. It almost cuts the time to run the tests in half. |
|
@lcawl, I think you should also have a look at this one, at last the README changes and the description. |
|
OK @olksdr, I think this is ready for you when you have time. |
| @@ -531,7 +555,7 @@ sub init_target_repo { | |||
| my ( $repos_dir, $temp_dir, $reference_dir ) = @_; | |||
|
|
|||
| my $target_repo = ES::TargetRepo->new( | |||
| dir => $repos_dir, | |||
| git_dir => $repos_dir->subdir('target_repo.git'), | |||
There was a problem hiding this comment.
Thins name target_repo.git is hardcoded. Can it be either supplied into the init_target_repo sub or maybe better randomly generated ?
maybe something like
my $repo_name = sub { join"", @_[ map{ rand @_ } 1 .. shift ] }->(10, "a".."z") . ".git";
# $repo_name should contain something like "cbhbprlxye.git"because I kind of never trust those hard coded names which can lead to some strange race conditions in the future if you want to run things in parallel
There was a problem hiding this comment.
I this case we really prefer to keep this in a stable place because it prevents us from having to pull as much.
Long before I got to it build_docs --all sacrificed being run in parallel for less git traffic. For the most part we don't want to run it in parallel anyway because its job is to commit to a particular repository.
There was a problem hiding this comment.
I see. Thanks for the explanation! Then it doesn't really matter 😄
lib/ES/BaseRepo.pm
Outdated
| @@ -34,7 +32,7 @@ sub new { | |||
|
|
|||
| return bless { | |||
| name => $name, | |||
| git_dir => $dir->subdir("$name.git"), | |||
| git_dir => $args{git_dir}, | |||
There was a problem hiding this comment.
Do we want to check that git_dir is definitely provided (the same like with name and url)?
There was a problem hiding this comment.
I haven't found that to be too useful, but sure!
| keep_hash => 0, | ||
| ); | ||
| $self->{dir} = $dir; | ||
| return $self; |
There was a problem hiding this comment.
I think you still need to bless the instance before returning it. Something like
return bless $self, $class;But can be that it gets blessed from the parent
There was a problem hiding this comment.
The parent blesses it, yeah.
lib/ES/Repo.pm
Outdated
| "Remote branch <origin/$branch> doesn't exist in repo " | ||
| . $self->name); | ||
| } | ||
| my $new_info = $new; | ||
| $new_info .= '|asciidoctor' if $asciidoctor; | ||
| say "ASDFADF " . $self->{name} . " $branch $path $old_info -> $new_info"; |
|
Let's get this in! Thanks @olksdr! |
This adds two features that are sort of interlinked in their
implementation but not so much in their use. We want them both though, I
think:
are rebuilt when those files are changed.
a lot of the
../../../../paths unneeded.So the second feature allows you to write includes like:
instead of:
The first feature combined with the second feature lets you write this
to include the shared files:
instead of:
Which is nice. In addition, the first feature lets you write:
in
conf.yamlto cause a book to be rebuilt if either:attributes.asciidocchangesshared/versions/stack/master.asciidocchanges. Assuming we'rebuilding the master branch of the book. It'll be
7.x.asciidocif we'rebuilding
7.x, etc.You can also declare a dependency on
shared/versions/stack/current.asciidocand we'll cause a rebuild ifeither
current.asciidocchanges to point to a new file or the filethat it points to changes.