yetus-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sean Busbey <bus...@apache.org>
Subject Re: [Discuss] Documentation Internal References?
Date Wed, 30 Oct 2019 04:30:59 GMT
Thanks for bringing up these issues Clay. The website has been a
source of consternation for awhile. I'll try to answer stuff below,
but in general if you have opinions on moving this stuff around I know
we'd be game.


On Tue, Oct 22, 2019 at 12:31 AM Clay B. <cwb@clayb.net> wrote:
>
> I have expanded the docs for those who come after me searching to
> manipulate their docker arguments and put some ideas in
> YETUS-921 but was wondering on how docs should be handled:
>
> 1. I highlight the add_docker_build_arg and add_docker_env functions
> linking to the auto-generated shelldocs. Is there a way in the docs build
> to point from the markdown to the shelldocs in a stable way other than
> assuming the documentation layout (e.g.
> ../precommit-apidocs/core/#<function>)?

This is a big lack in our current set up I think. AFAIK there's no way
to do this that doesn't require you to make assumptions about layout
because we don't have any kind of abstraction on top of the tools we
make.


>
> 2. I see on Yetus.Apache.ORG index.html is the DirectoryIndex, but of
> course when browsing the docs locally, one must add index.html to URLs
> (or use a webserver like the main docs site to redirect to it e.g. for
> precommit-apidocs/core/#add_docker_build_arg vs
> precommit-apidocs/core/index.html#add_docker_build_arg); which is
> preferred in the markdown?
>

the directory without hte index.html. I think our contributing guide
for working with the website already points folks towards running a
local webserver. we should optimize for that.

> 3. As I was originally confused on how I would use a
> <personality>_docker_support function in my personality file and finding a
> few different nuggets, I added hyperlinks between
> precommit-advanced.html.md and precommit-buildtools.html.md. Both talk
> about the same extension points. Is there an idea to canonicalize the docs
> between precommit-buildtools and precommit-advanced or can cross-linking
> be a reasonable shim to ensure a newbie gets a complete picture?
>
>

you tell us. :) AFAIK all of the current docs were put together by
folks already years into using yetus. we could definitely use feedback
from more folks starting from the other side of the codebase.

Mime
View raw message