[reminder] Build and check the documentation when reviewing

[Seth Wiesman-4]

Hi Devs,

First of all, I'd like to thank everyone for being more proactive about
writing documentation along with their features. Compared to previous
releases there is not so much last-minute documentation writing and that is
something to be celebrated!

That said, we are still beginning to see an influx in documentation PRs and
I would just like to remind the committers to always build the
documentation locally when reviewing non trivial changes. This practice
helps ensure any inline liquid tags or HTML properly renders. Additionally,
if new pages or links are being added you may run the
`./docs/check_links.sh` script to test for broken links. Documentation is
most users' first introduction to Flink so it is important we provide them
a pleasant experience.

Finally, if you are ever unsure how something should be phrased or
formatted please refer to the contribution guidelines or feel free to ping
me directly[1].

Cheers,

Seth

[1] https://flink.apache.org/contributing/docs-style.html

[Xintong Song]

Thanks for the reminder, Seth.

The `check_links.sh` script is helpful, and I was not aware of it.

Do you think it makes sense to also mention the script in
`flink-docs/README.md`? So that future developers could also be aware of
it. Or is it already mentioned somewhere that I overlooked?

Thank you~

Xintong Song



On Tue, Nov 10, 2020 at 9:03 AM Seth Wiesman <[hidden email]> wrote:

> Hi Devs,
>
> First of all, I'd like to thank everyone for being more proactive about
> writing documentation along with their features. Compared to previous
> releases there is not so much last-minute documentation writing and that is
> something to be celebrated!
>
> That said, we are still beginning to see an influx in documentation PRs and
> I would just like to remind the committers to always build the
> documentation locally when reviewing non trivial changes. This practice
> helps ensure any inline liquid tags or HTML properly renders. Additionally,
> if new pages or links are being added you may run the
> `./docs/check_links.sh` script to test for broken links. Documentation is
> most users' first introduction to Flink so it is important we provide them
> a pleasant experience.
>
> Finally, if you are ever unsure how something should be phrased or
> formatted please refer to the contribution guidelines or feel free to ping
> me directly[1].
>
> Cheers,
>
> Seth
>
> [1] https://flink.apache.org/contributing/docs-style.html
>

[Dian Fu-2]

Thanks a lot for the reminder, Seth.

What about integrating this script in the azure pipeline? There is a "Documentation links check" in travis before: https://travis-ci.org/github/apache/flink/jobs/742553633 <https://travis-ci.org/github/apache/flink/jobs/742553633>

Thanks,
Dian

> 在 2020年11月10日，上午9:39，Xintong Song <[hidden email]> 写道：
>
> Thanks for the reminder, Seth.
>
> The `check_links.sh` script is helpful, and I was not aware of it.
>
> Do you think it makes sense to also mention the script in
> `flink-docs/README.md`? So that future developers could also be aware of
> it. Or is it already mentioned somewhere that I overlooked?
>
> Thank you~
>
> Xintong Song
>
>
>
> On Tue, Nov 10, 2020 at 9:03 AM Seth Wiesman <[hidden email]> wrote:
>
>> Hi Devs,
>>
>> First of all, I'd like to thank everyone for being more proactive about
>> writing documentation along with their features. Compared to previous
>> releases there is not so much last-minute documentation writing and that is
>> something to be celebrated!
>>
>> That said, we are still beginning to see an influx in documentation PRs and
>> I would just like to remind the committers to always build the
>> documentation locally when reviewing non trivial changes. This practice
>> helps ensure any inline liquid tags or HTML properly renders. Additionally,
>> if new pages or links are being added you may run the
>> `./docs/check_links.sh` script to test for broken links. Documentation is
>> most users' first introduction to Flink so it is important we provide them
>> a pleasant experience.
>>
>> Finally, if you are ever unsure how something should be phrased or
>> formatted please refer to the contribution guidelines or feel free to ping
>> me directly[1].
>>
>> Cheers,
>>
>> Seth
>>
>> [1] https://flink.apache.org/contributing/docs-style.html
>>

[Robert Metzger]

Thank you Seth!

@Dian: It is part of the nightly scheduled build:
https://dev.azure.com/apache-flink/apache-flink/_build/results?buildId=9361&view=logs&j=6dc02e5c-5865-5c6a-c6c5-92d598e3fc43

On Tue, Nov 10, 2020 at 2:50 AM Dian Fu <[hidden email]> wrote:

> Thanks a lot for the reminder, Seth.
>
> What about integrating this script in the azure pipeline? There is a
> "Documentation links check" in travis before:
> https://travis-ci.org/github/apache/flink/jobs/742553633 <
> https://travis-ci.org/github/apache/flink/jobs/742553633>
>
> Thanks,
> Dian
>
> > 在 2020年11月10日，上午9:39，Xintong Song <[hidden email]> 写道：
> >
> > Thanks for the reminder, Seth.
> >
> > The `check_links.sh` script is helpful, and I was not aware of it.
> >
> > Do you think it makes sense to also mention the script in
> > `flink-docs/README.md`? So that future developers could also be aware of
> > it. Or is it already mentioned somewhere that I overlooked?
> >
> > Thank you~
> >
> > Xintong Song
> >
> >
> >
> > On Tue, Nov 10, 2020 at 9:03 AM Seth Wiesman <[hidden email]>
> wrote:
> >
> >> Hi Devs,
> >>
> >> First of all, I'd like to thank everyone for being more proactive about
> >> writing documentation along with their features. Compared to previous
> >> releases there is not so much last-minute documentation writing and
> that is
> >> something to be celebrated!
> >>
> >> That said, we are still beginning to see an influx in documentation PRs
> and
> >> I would just like to remind the committers to always build the
> >> documentation locally when reviewing non trivial changes. This practice
> >> helps ensure any inline liquid tags or HTML properly renders.
> Additionally,
> >> if new pages or links are being added you may run the
> >> `./docs/check_links.sh` script to test for broken links. Documentation
> is
> >> most users' first introduction to Flink so it is important we provide
> them
> >> a pleasant experience.
> >>
> >> Finally, if you are ever unsure how something should be phrased or
> >> formatted please refer to the contribution guidelines or feel free to
> ping
> >> me directly[1].
> >>
> >> Cheers,
> >>
> >> Seth
> >>
> >> [1] https://flink.apache.org/contributing/docs-style.html
> >>
>
>

[Dian Fu-2]

Thanks @Robert for this info.

It seems that there is some problem with the "docs_404_check". From the log we can see that the doc server wasn't started up after 5 minutes and the test just exits. Have created a ticket https://issues.apache.org/jira/browse/FLINK-20069 <https://issues.apache.org/jira/browse/FLINK-20069> to track this issue.

Thanks,
Dian

> 在 2020年11月10日，下午2:23，Robert Metzger <[hidden email]> 写道：
>
> Thank you Seth!
>
> @Dian: It is part of the nightly scheduled build:
> https://dev.azure.com/apache-flink/apache-flink/_build/results?buildId=9361&view=logs&j=6dc02e5c-5865-5c6a-c6c5-92d598e3fc43
>
> On Tue, Nov 10, 2020 at 2:50 AM Dian Fu <[hidden email]> wrote:
>
>> Thanks a lot for the reminder, Seth.
>>
>> What about integrating this script in the azure pipeline? There is a
>> "Documentation links check" in travis before:
>> https://travis-ci.org/github/apache/flink/jobs/742553633 <
>> https://travis-ci.org/github/apache/flink/jobs/742553633>
>>
>> Thanks,
>> Dian
>>
>>> 在 2020年11月10日，上午9:39，Xintong Song <[hidden email]> 写道：
>>>
>>> Thanks for the reminder, Seth.
>>>
>>> The `check_links.sh` script is helpful, and I was not aware of it.
>>>
>>> Do you think it makes sense to also mention the script in
>>> `flink-docs/README.md`? So that future developers could also be aware of
>>> it. Or is it already mentioned somewhere that I overlooked?
>>>
>>> Thank you~
>>>
>>> Xintong Song
>>>
>>>
>>>
>>> On Tue, Nov 10, 2020 at 9:03 AM Seth Wiesman <[hidden email]>
>> wrote:
>>>
>>>> Hi Devs,
>>>>
>>>> First of all, I'd like to thank everyone for being more proactive about
>>>> writing documentation along with their features. Compared to previous
>>>> releases there is not so much last-minute documentation writing and
>> that is
>>>> something to be celebrated!
>>>>
>>>> That said, we are still beginning to see an influx in documentation PRs
>> and
>>>> I would just like to remind the committers to always build the
>>>> documentation locally when reviewing non trivial changes. This practice
>>>> helps ensure any inline liquid tags or HTML properly renders.
>> Additionally,
>>>> if new pages or links are being added you may run the
>>>> `./docs/check_links.sh` script to test for broken links. Documentation
>> is
>>>> most users' first introduction to Flink so it is important we provide
>> them
>>>> a pleasant experience.
>>>>
>>>> Finally, if you are ever unsure how something should be phrased or
>>>> formatted please refer to the contribution guidelines or feel free to
>> ping
>>>> me directly[1].
>>>>
>>>> Cheers,
>>>>
>>>> Seth
>>>>
>>>> [1] https://flink.apache.org/contributing/docs-style.html
>>>>
>>
>>