metron-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Casey Stella <>
Subject Re: [DISCUSS] Metron documentation improvements
Date Thu, 20 Dec 2018 20:08:04 GMT
I definitely agree with option 3; that's a no-brainer IMO.  I thought for
sure this was already happening, honestly.

As for 2, we could even script the broken link check by:

   - Serving up the site locally via python with `python -m http.server`
   from the site-book output directory
   - Looking at the output of wget --spider -e robots=off -w 1 -r -p
   http://localhost:8000 for 404s

As for 1, I'm fine with it if that's where we want to go.  I'm a +0

On Thu, Dec 20, 2018 at 2:47 PM Michael Miklavcic <> wrote:

> We recently had our site-book doc generation break due to our not including
> it in the Travis build. The fix for a broken build seems simple enough -
> add it to our build process and assuming it doesn't cause build timeout
> issues, we should be good to go.
> Beyond that, there are additional issues with the existing process. We have
> a step in our PR review for validating that the docs are rendering
> properly. I know I've gone back and corrected issues with broken images or
> incorrectly rendering pages at least a few times now. On one hand, we might
> say this is simply a matter of being better about validating documentation
> during the review process. That may be true, but rather than fight upstream
> like a salmon, I would prefer to simplify things, automate what we can, and
> use technology to work with us. Based on this conversation on METRON-1950 -
> (
> ),
> I'd like to open up a general convo about improvements to our documentation
> generation.
> *Current Issues:*
>    1. Duplicated effort - have to check pages render in Github and the
>    Doxia-generated site-book
>    2. Inconsistent model - what works for Github markdown may not work for
>    Doxia, and vice versa
>    3. Github is part of our workflow and easy to check, Doxia requires an
>    extra separate step - suffers unintentional bugs due to #2.
>    4. Images have to be manually added to the site rendering code for
>    copying to the "images" folder, and explicit src ref replacements have
> to
>    be included for all affected pages/links as well.
>    5. Page links and images are not validated - this currently requires
>    manual review and intervention during PR review and whenever we create a
>    new Metron release.
>    6. Failed site-book build is not validated. Broken build does not fail
>    Travis
> *Options and Solutions:*
>    1. Otto has already brought up using Ascii doc as one option for solving
>    a number of these issues.
>    2. For issue #5, we can write a scraper that validates links or use
>    tooling like Cypress for this.
>    3. For issue #6, we can add site-book building to our Travis runs. It's
>    pretty quick to generate and will catch the more egregious rendering
> bugs.
>    I plan to look at this presently.
> Mike

  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message