From dev-return-1688-archive-asf-public=cust-asf.ponee.io@yetus.apache.org Tue Oct 22 05:31:35 2019 Return-Path: X-Original-To: archive-asf-public@cust-asf.ponee.io Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [207.244.88.153]) by mx-eu-01.ponee.io (Postfix) with SMTP id 7A71618062C for ; Tue, 22 Oct 2019 07:31:35 +0200 (CEST) Received: (qmail 35321 invoked by uid 500); 22 Oct 2019 05:31:34 -0000 Mailing-List: contact dev-help@yetus.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@yetus.apache.org Delivered-To: mailing list dev@yetus.apache.org Received: (qmail 35307 invoked by uid 99); 22 Oct 2019 05:31:33 -0000 Received: from pnap-us-west-generic-nat.apache.org (HELO spamd2-us-west.apache.org) (209.188.14.142) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 22 Oct 2019 05:31:33 +0000 Received: from localhost (localhost [127.0.0.1]) by spamd2-us-west.apache.org (ASF Mail Server at spamd2-us-west.apache.org) with ESMTP id 1A03C1A3286 for ; Tue, 22 Oct 2019 05:31:33 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at spamd2-us-west.apache.org X-Spam-Flag: NO X-Spam-Score: -0.199 X-Spam-Level: X-Spam-Status: No, score=-0.199 tagged_above=-999 required=6.31 tests=[DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=disabled Authentication-Results: spamd2-us-west.apache.org (amavisd-new); dkim=pass (1024-bit key) header.d=clayb.net Received: from mx1-ec2-va.apache.org ([10.40.0.8]) by localhost (spamd2-us-west.apache.org [10.40.0.9]) (amavisd-new, port 10024) with ESMTP id 7cGLxnkgvaXK for ; Tue, 22 Oct 2019 05:31:30 +0000 (UTC) Received-SPF: Pass (mailfrom) identity=mailfrom; client-ip=23.83.209.25; helo=bumble.birch.relay.mailchannels.net; envelope-from=cwb@clayb.net; receiver= Received: from bumble.birch.relay.mailchannels.net (bumble.birch.relay.mailchannels.net [23.83.209.25]) by mx1-ec2-va.apache.org (ASF Mail Server at mx1-ec2-va.apache.org) with ESMTPS id A9AB4BC677 for ; Tue, 22 Oct 2019 05:24:02 +0000 (UTC) X-Sender-Id: dreamhost|x-authsender|cwb@clayb.net Received: from relay.mailchannels.net (localhost [127.0.0.1]) by relay.mailchannels.net (Postfix) with ESMTP id ED9F0580B1F for ; Tue, 22 Oct 2019 05:23:54 +0000 (UTC) Received: from pdx1-sub0-mail-a67.g.dreamhost.com (100-96-91-110.trex.outbound.svc.cluster.local [100.96.91.110]) (Authenticated sender: dreamhost) by relay.mailchannels.net (Postfix) with ESMTPA id 8E549580ACF for ; Tue, 22 Oct 2019 05:23:54 +0000 (UTC) X-Sender-Id: dreamhost|x-authsender|cwb@clayb.net Received: from pdx1-sub0-mail-a67.g.dreamhost.com ([TEMPUNAVAIL]. [64.90.62.162]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384) by 0.0.0.0:2500 (trex/5.18.5); Tue, 22 Oct 2019 05:23:54 +0000 X-MC-Relay: Neutral X-MailChannels-SenderId: dreamhost|x-authsender|cwb@clayb.net X-MailChannels-Auth-Id: dreamhost X-Decisive-Snatch: 007644ce0230fd8f_1571721834792_2096873766 X-MC-Loop-Signature: 1571721834792:799777751 X-MC-Ingress-Time: 1571721834791 Received: from pdx1-sub0-mail-a67.g.dreamhost.com (localhost [127.0.0.1]) by pdx1-sub0-mail-a67.g.dreamhost.com (Postfix) with ESMTP id 129DE85EFA for ; Mon, 21 Oct 2019 22:23:49 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=clayb.net; h=date:from:to :subject:message-id:mime-version:content-type; s=clayb.net; bh=a KG+PHNgUsREJ1W/39iI2IFVaug=; b=PXMHce6t5qilnbOm18U8OzwdlknO7c621 1pyinIFCY8OQybvIzLbBktHFKBay8/Nnsk7iz+nmbo2IP5ccTGlSzXduvboc8/DE 3Um2F14RxTZQYzjrvB9uGqR1bKt2rKa+JmicTnKa0TeBXfFlbpf/ZRD3mB2AjE8x GloPGOHtL4= Received: from sussex.dreamhost.com (sussex.dreamhost.com [208.113.171.60]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) (Authenticated sender: cwb@clayb.net) by pdx1-sub0-mail-a67.g.dreamhost.com (Postfix) with ESMTPSA id 8613F85EDB for ; Mon, 21 Oct 2019 22:23:48 -0700 (PDT) Date: Mon, 21 Oct 2019 22:23:47 -0700 (PDT) X-DH-BACKEND: pdx1-sub0-mail-a67 From: "Clay B." To: dev@yetus.apache.org Subject: [Discuss] Documentation Internal References? Message-ID: MIME-Version: 1.0 Content-Type: text/plain; format=flowed; charset=US-ASCII 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/#)? 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? 3. As I was originally confused on how I would use a _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? -Clay