Noissue - Add [paths] documentation and remove trailing spaces

Noissue - Add [paths] documentation and remove trailing spaces

[rhowell, 2019-01-10 01:28:10]

Just some minor clean-up of the docs. Let me know if there's a better way to
phrase the `additional-paths` info in `settings.md`?

[Vasily Kuznetsov, 2019-01-10 16:39:46]

Hi Rosie,

Thank you for the fixes. One additional suggestion below.

Cheers,
Vasily

https://codereview.adblockplus.org/29977630/diff/29977631/docs/content/settin...
File docs/content/settings.md (right):

https://codereview.adblockplus.org/29977630/diff/29977631/docs/content/settin...
docs/content/settings.md:22: * '[paths]': Optionally, this can be used to add
additional root folders. E.g.
I think it would be useful to explain the main use case of this feature:
something like "website inheritance" where we can put parts common to multiple
websites into a separate repository and then reference them from each of the
sharing websites. Let me know if you need help with more details about this or
with drafting the text.

[rhowell, 2019-01-10 20:52:59]

https://codereview.adblockplus.org/29977630/diff/29977631/docs/content/settin...
File docs/content/settings.md (right):

https://codereview.adblockplus.org/29977630/diff/29977631/docs/content/settin...
docs/content/settings.md:22: * '[paths]': Optionally, this can be used to add
additional root folders. E.g.
On 2019/01/10 16:39:46, Vasily Kuznetsov wrote:
> I think it would be useful to explain the main use case of this feature:
> something like "website inheritance" where we can put parts common to multiple
> websites into a separate repository and then reference them from each of the
> sharing websites. Let me know if you need help with more details about this or
> with drafting the text.

I gave it a shot, but feel free to add or change anything you want!

[rhowell, 2019-01-11 19:22:15]

On 2019/01/10 20:52:59, rhowell wrote:
>
https://codereview.adblockplus.org/29977630/diff/29977631/docs/content/settin...
> File docs/content/settings.md (right):
> 
>
https://codereview.adblockplus.org/29977630/diff/29977631/docs/content/settin...
> docs/content/settings.md:22: * '[paths]': Optionally, this can be used to add
> additional root folders. E.g.
> On 2019/01/10 16:39:46, Vasily Kuznetsov wrote:
> > I think it would be useful to explain the main use case of this feature:
> > something like "website inheritance" where we can put parts common to
multiple
> > websites into a separate repository and then reference them from each of the
> > sharing websites. Let me know if you need help with more details about this
or
> > with drafting the text.
> 
> I gave it a shot, but feel free to add or change anything you want!

I noticed a couple more things missing from the documentation, about global
functions and siteurl, so I just tacked them on to this Noissue and changed the
commit message to 'Add [paths] and global functions documentation'. Is that
commit message ok, or should I also mention removing the trailing whitespaces?

[Vasily Kuznetsov, 2019-01-14 14:04:32]

Hi Rosie,

Thanks for more docs, this is great!

See my comment on the paths/additional-paths.

Cheers,
Vasily

https://codereview.adblockplus.org/29977630/diff/29978568/docs/content/settin...
File docs/content/settings.md (right):

https://codereview.adblockplus.org/29977630/diff/29978568/docs/content/settin...
docs/content/settings.md:22: * '[paths]': A root folder of another website may
be specified here, which will
I think it would be easier to read if separate the section description and key
description, even though there's only one key. Also I think mentioning "remote
resources" and "repositories" could be confusing so I tried to rewrite it only
mentioning websites and directories (it seems that we use "directory" instead of
"folder" in the rest of the docs, so I tried to be consistent):

* `[paths]`: Configure where things are located on the filesystem:
  * `additional-paths`: One or more additional website root directories (paths
should be relative to the root directory of this website). Pages, templates,
translations, etc. from those websites will be added to this one. This is useful
for sharing common resources between multiple websites.

Feel free to correct further if something sounds odd or unclear.

[rhowell, 2019-01-14 15:11:30]

https://codereview.adblockplus.org/29977630/diff/29978568/docs/content/settin...
File docs/content/settings.md (right):

https://codereview.adblockplus.org/29977630/diff/29978568/docs/content/settin...
docs/content/settings.md:22: * '[paths]': A root folder of another website may
be specified here, which will
On 2019/01/14 14:04:31, Vasily Kuznetsov wrote:
> I think it would be easier to read if separate the section description and key
> description, even though there's only one key. Also I think mentioning "remote
> resources" and "repositories" could be confusing so I tried to rewrite it only
> mentioning websites and directories (it seems that we use "directory" instead
of
> "folder" in the rest of the docs, so I tried to be consistent):
> 
> * `[paths]`: Configure where things are located on the filesystem:
>   * `additional-paths`: One or more additional website root directories (paths
> should be relative to the root directory of this website). Pages, templates,
> translations, etc. from those websites will be added to this one. This is
useful
> for sharing common resources between multiple websites.
> 
> Feel free to correct further if something sounds odd or unclear.

Yeah, this layout seems to be more clear. Thanks!

[Vasily Kuznetsov, 2019-01-14 16:33:15]

Just a little nit and all good otherwise.

https://codereview.adblockplus.org/29977630/diff/29981562/docs/content/settin...
File docs/content/settings.md (right):

https://codereview.adblockplus.org/29977630/diff/29981562/docs/content/settin...
docs/content/settings.md:25: should be relative to the root directory of this
website). Pages, templates,
Nit: The following lines of the bullet item should be indented the same as the
first lines (see other bullet items).

[rhowell, 2019-01-14 17:21:09]

https://codereview.adblockplus.org/29977630/diff/29981562/docs/content/settin...
File docs/content/settings.md (right):

https://codereview.adblockplus.org/29977630/diff/29981562/docs/content/settin...
docs/content/settings.md:25: should be relative to the root directory of this
website). Pages, templates,
On 2019/01/14 16:33:15, Vasily Kuznetsov wrote:
> Nit: The following lines of the bullet item should be indented the same as the
> first lines (see other bullet items).

Oops! Thanks for catching that.

[Vasily Kuznetsov, 2019-01-16 10:24:06]

https://codereview.adblockplus.org/29977630/diff/29981562/docs/content/settin...
File docs/content/settings.md (right):

https://codereview.adblockplus.org/29977630/diff/29981562/docs/content/settin...
docs/content/settings.md:25: should be relative to the root directory of this
website). Pages, templates,
On 2019/01/14 17:21:08, rhowell wrote:
> On 2019/01/14 16:33:15, Vasily Kuznetsov wrote:
> > Nit: The following lines of the bullet item should be indented the same as
the
> > first lines (see other bullet items).
> 
> Oops! Thanks for catching that.

Sorry to be annoying, but the following lines are now indented to the same level
as the bullet of the list. They should be indented 2 spaces more to start at the
same position as the text of the first line. I know that Markdown doesn't care
but all other lists are indented this way so it would look better if we were
consistent.

[rhowell, 2019-01-17 02:52:40]

Hi Vasily,

Thanks for catching that (again).

https://codereview.adblockplus.org/29977630/diff/29981562/docs/content/settin...
File docs/content/settings.md (right):

https://codereview.adblockplus.org/29977630/diff/29981562/docs/content/settin...
docs/content/settings.md:25: should be relative to the root directory of this
website). Pages, templates,
On 2019/01/16 10:24:05, Vasily Kuznetsov wrote:
> On 2019/01/14 17:21:08, rhowell wrote:
> > On 2019/01/14 16:33:15, Vasily Kuznetsov wrote:
> > > Nit: The following lines of the bullet item should be indented the same as
> the
> > > first lines (see other bullet items).
> > 
> > Oops! Thanks for catching that.
> 
> Sorry to be annoying, but the following lines are now indented to the same
level
> as the bullet of the list. They should be indented 2 spaces more to start at
the
> same position as the text of the first line. I know that Markdown doesn't care
> but all other lists are indented this way so it would look better if we were
> consistent.

Sheesh, that's what I get for rushing! Sorry bout that.

[Vasily Kuznetsov, 2019-01-17 10:05:04]

Now it all looks perfect ;)
LGTM