From patchwork Tue Dec 13 17:57:24 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Finucane X-Patchwork-Id: 705482 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from mail.linuxfoundation.org (mail.linuxfoundation.org [140.211.169.12]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 3tdS9h1zjBz9sCM for ; Wed, 14 Dec 2016 04:58:16 +1100 (AEDT) Authentication-Results: ozlabs.org; dkim=fail reason="key not found in DNS" (0-bit key; unprotected) header.d=that.guru header.i=@that.guru header.b="mNbp+0J2"; dkim-atps=neutral Received: from mail.linux-foundation.org (localhost [127.0.0.1]) by mail.linuxfoundation.org (Postfix) with ESMTP id 3BC7ABEB; Tue, 13 Dec 2016 17:58:01 +0000 (UTC) X-Original-To: dev@openvswitch.org Delivered-To: ovs-dev@mail.linuxfoundation.org Received: from smtp1.linuxfoundation.org (smtp1.linux-foundation.org [172.17.192.35]) by mail.linuxfoundation.org (Postfix) with ESMTPS id D0849BDF for ; Tue, 13 Dec 2016 17:57:59 +0000 (UTC) X-Greylist: from auto-whitelisted by SQLgrey-1.7.6 Received: from nov-007-i609.relay.mailchannels.net (nov-007-i609.relay.mailchannels.net [46.232.183.163]) by smtp1.linuxfoundation.org (Postfix) with ESMTPS id 68834141 for ; Tue, 13 Dec 2016 17:57:46 +0000 (UTC) X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from relay.mailchannels.net (localhost [127.0.0.1]) by relay.mailchannels.net (Postfix) with ESMTP id 792FB21661 for ; Tue, 13 Dec 2016 17:57:41 +0000 (UTC) Received: from one.mxroute.com (ip-10-27-139-41.us-west-2.compute.internal [10.27.139.41]) by relay.mailchannels.net (Postfix) with ESMTPA id 74A3621F89 for ; Tue, 13 Dec 2016 17:57:40 +0000 (UTC) X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from one.mxroute.com ([UNAVAILABLE]. [10.16.27.41]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384) by 0.0.0.0:2500 (trex/5.7.8); Tue, 13 Dec 2016 17:57:41 +0000 X-MC-Relay: Neutral X-MailChannels-SenderId: mxroute|x-authuser|stephen@that.guru X-MailChannels-Auth-Id: mxroute X-MC-Loop-Signature: 1481651860805:1487354090 X-MC-Ingress-Time: 1481651860804 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=that.guru; s=default; h=References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Sender:Reply-To:MIME-Version:Content-Type:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=xUIk0QiyleUm4olHIehlsWGgATnfmhwc2QsBl2H0HBA=; b=mNbp+0J2zRYDlP80/yOKk+9mHt j4rCwdAu6tyXGJz+T7Sh2btt3Qk6C+ZWX6mdNQ35BohSpYCrGFZkkwX8xaDGjCYJngEm3YJ2OcwKV GQfmC0fPgvlMOqj9sQtLAM7A4DJyhLPZC3GVQhta7JriyTwZ8SR61KN0S/ISwxiLU+HAooZMjo7kJ nn0pdG4mNOrRwLVMdTaES1K/cETPOpOAecHTmqoIxmPDKOLzEWiiSca38/47DEFkZlZtoZoTJojAt LEKpzq0TAg6vi/WtzLaabW4cWTePkibGsKrmefXbDNcnmxQgQZogePygw5XaVimtKRqCSKKis8H8X Uroc9ZsQ==; From: Stephen Finucane To: dev@openvswitch.org Date: Tue, 13 Dec 2016 17:57:24 +0000 Message-Id: <20161213175724.17447-5-stephen@that.guru> X-Mailer: git-send-email 2.9.3 In-Reply-To: <20161213175724.17447-1-stephen@that.guru> References: <20161213175724.17447-1-stephen@that.guru> X-AuthUser: stephen@that.guru X-Spam-Status: No, score=-1.8 required=5.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_NONE,T_DKIM_INVALID autolearn=no version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on smtp1.linux-foundation.org Subject: [ovs-dev] [PATCH 4/4] Merge docs into README X-BeenThere: ovs-dev@openvswitch.org X-Mailman-Version: 2.1.12 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Sender: ovs-dev-bounces@openvswitch.org Errors-To: ovs-dev-bounces@openvswitch.org More readable. Less weird filenames. Winning. Signed-off-by: Stephen Finucane --- README.md | 156 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- _BUILD | 28 ----------- _DOC | 78 ------------------------------- _TODO | 40 ---------------- 4 files changed, 149 insertions(+), 153 deletions(-) delete mode 100644 _BUILD delete mode 100644 _DOC delete mode 100644 _TODO diff --git a/README.md b/README.md index 27a4b31..3f9952f 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,152 @@ -openvswitch.github.io -===================== +# openvswitch.github.io -Website for Open vSwitch. +Website for Open vSwitch. This is written in Jekyll. We use: -Documentation: +- the templating engine, to format yaml data into html (for the navbar), to use + jekyll variables (`page.url`, `site.url`, `page.title`) -* **\_BUILD**: How to generate the website HTML from Jekyll sources. -* **\_DOC**: Architecture of the website (layouts, directories, ...). -* **\_TODO**: Unfinished features and improvements. +- the layout mechanism. Each page includes only its specific content and + declare its layout (which is a html file that contains the logo, the navbar, + the footer...) + +We do not use: + +- blog specific mechanisms: we do not have blogs, we do not have posts. We do + not have a `_post/` directory. + +## Development + +You can develop using `docker-compose`: + + $ docker-compose up + +You should see your site at http://localhost:4000/ + +Alternatively, install the Jekyll dependencies (2.x only, for now), then run: + + $ jekyll server -w + +in the main site directory. This will be available at the +http://localhost:4000/ + +## Deployment + +GitHub pages supports Jekyll without any further changes. To deploy locally, +run: + + $ jekyll build + +in the main site directory. This will output to `_site/`, the contents of which +can be exported with any static HTTP server. + +## Design + +### Layouts + +The skel (`_layouts/skel.html`) layout contains the header (logo+navbar) and +the footer. Only the home page uses this. + +The page (`_layouts/page.html`) layout "inherits" from the skel layout and adds +a series of widgets (updates, recent releases, ...) and the title inside the +mainpage div. Almost every page uses this. + +The pagenosidewidget (`_layouts/pagenosidewidget.html`) layout "inherits" from +the skel layout and adds only the title inside the mainpage div. + +The CSS that we use is inspired by the wordpress output (but it's supposed to +be directly maintainable). It uses heavily fixed sized elements (i.e. we +explicitly specify the size in px). + +Layouts rely on includes + +### Includes + +We use includes to split html in multiple files. For example the side widgets +are on `_include/side_widgets.html`. + +### Navigation bar + +- Style + + The navbar is only a nested series of `
  • ` elements (this is in line + with current best practices). The navbar display behavior (display/hide + submenus) is implemented only in CSS, in a style tag inside header.html. It + should support an unlimited number of nested submenus + +- Content: + + Jekyll (at least the safe version used by github pages) does not support a + way to generate a page list. Therefore we manually list the pages that we + want to appear in the navbar (in order) in `_data/nav.yml`. The url attribute + is relative to the parent page. A bit of templating magic (recursively + including `menulist.html`, with different `include.*` variables) allows us to + generate the `
    • ` elements + +The skel layout includes `_includes/header.html` which includes +`_includes/menulist.html`. + +### Pages + +Jekyll allows us to write page content in html or markdown. Most of the pages +are HTML now, since that is the output of the wordpress importer. Pages that +require advanced styling (e.g. the homepage) should be in html too. + +Currently all the pages use a directory URL (e.g. +http://openvswitch.org/support/) The page is stored in a file called index.html +(or index.markdown) + +Each page has a yaml preamble that contains the title, the layout that we want, +and some other information extracted by wordpress that it might be worth +keeping. + +## TODO + +- Refine style: + + Test with many browsers + +- Navigation summary (under the navbar) + + A > B > C + +- There are some TODO in the files. grep for them + +- Remove useless info from the preamble? (author, ...) + +## Open issues + +1) Releases + + This repository currently does not host ovs releases as the oldwebsite did. + + Proposals: + + a) do not host them. Let github generate the files through tags + + + simple + + - Is github reliable? does the file change? Some user might expect it to + have a consistent hash + + b) upload them to the website git repository + +2) /cgi-bin/man + + There was a script on the old website that generated updated (from master) + man pages (in PDF and HTML). There are some links to these pages somewhere + on the website. Proposals: + + a) upload static version of the manpages + + - they do not get updated + +3) /pipermail/ + + `http://openvswitch.org/pipermail` is the mailman archive. If we use github + hosting, openvswitch.org will be a CNAME for `openvswitch.github.io` (or + something similar). Since we do not have control over + `openvswitch.github.io` we cannot redirect `/pipermail/*` to something else. + +4) google analytics + + include google analytics snippet diff --git a/_BUILD b/_BUILD deleted file mode 100644 index 3bd23c3..0000000 --- a/_BUILD +++ /dev/null @@ -1,28 +0,0 @@ -- Install jekyll - -Develop the website -------------------- - -- Run - jekyll serve -w - in the site main directory -- Go to http://localhost:4000/ - -Even though jekyll is a static site generator, when run with -w it will -monitor the source directory for changes and rebuild the website -automatically. - -Deploy the website ------------------- - -- Run - jekyll build - in the site main directory -- The output will be in the _site/ subdirectory. It can be exported - with any static HTTP server - -Deploy the website (github pages) ---------------------------------- - -Github pages support Jekyll. The site source code can be uploaded to a repo -and it will be automatically compiled and exported. diff --git a/_DOC b/_DOC deleted file mode 100644 index 273e186..0000000 --- a/_DOC +++ /dev/null @@ -1,78 +0,0 @@ -OVS Jekyll website ------------------- - -What we use of jekyll: - - the templating engine, to format yaml data into html (for the navbar), - to use jekyll variables (page.url, site.url, page.title) - - the layout mechanism. Each page includes only its specific content and - declare its layout (which is a html file that contains the logo, - the navbar, the footer...) -What we do not use: - - blog specific mechanisms: we do not have blogs, we do not have posts. - We do not have a _post/ directory. - - -Layouts -------- - -The skel (_layouts/skel.html) layout contains the header (logo+navbar) and -the footer. It displays it content into a center ~900px-wide div. It is -directly used only for the homepage. - -The page (_layouts/page.html) layout "inherits" from the skel layout and adds -a series of widgets (updates, recent releases, ...) and the title inside the -mainpage div. -Almost every page uses this. - -The pagenosidewidget (_layouts/pagenosidewidget.html.html) layout "inherits" -from the skel layout and adds only the title inside the mainpage div. - -The CSS that we use is inspired by the wordpress output (but it's supposed -to be directly maintainable). It uses heavily fixed sized elements (i.e. we -explicitly specify the size in px). - -Layouts rely on includes - - -Includes --------- - -We use includes to split html in multiple files. For example the side widgets -are on _include/side_widgets.html. - - -Navigation bar --------------- - -- Style: - The navbar is only a nested series of
      • elements (this is in line - with current best practices). - The navbar display behavior (display/hide submenus) is implemented only in - CSS, in a style tag inside header.html. It should support an unlimited - number of nested submenus - -- Content: - Jekyll (at least the safe version used by github pages) does not support - a way to generate a page list. Therefore we manually list the pages that - we want to appear in the navbar (in order) in _data/nav.yml. The url - attribute is relative to the parent page. - A bit of templating magic (recursively including menulist.html, with - different include.* variables) allows us to generate the
        • elements - -The skel layout includes _includes/header.html which includes -_includes/menulist.html - - -Pages ------ - -Jekyll allows us to write page content in html or markdown. Most of the pages -are HTML now, since that is the output of the wordpress importer. Pages that -require advanced styling (e.g. the homepage) should be in html too. - -Currently all the pages use a directory URL (e.g. http://openvswitch.org/support/) -The page is stored in a file called index.html (or index.markdown) - -Each page has a yaml preamble that contains the title, the layout that we -want, and some other information extracted by wordpress that it might be worth -keeping. diff --git a/_TODO b/_TODO deleted file mode 100644 index 38a6a29..0000000 --- a/_TODO +++ /dev/null @@ -1,40 +0,0 @@ -TODOS - -- Refine style: - test with many browsers - -- Navigation summary (under the navbar) ? - A > B > C - -- There are some TODO in the files. Please grep for them - -- Remove useless info from the preamble? (author, ...) - -- Remove (or prefix with "_") this TODO file - -OPEN ISSUES - -1) Releases - This repository currently does not host ovs releases as the oldwebsite did. - Proposals: - a) do not host them. Let github generate the files through tags - + simple - - Is github reliable? does the file change? Some user might - expect it to have a consistent hash - b) upload them to the website git repository - -2) /cgi-bin/man - There was a script on the old website that generated updated (from master) - man pages (in PDF and HTML). There are some links to these pages somewhere - on the website. Proposals: - a) upload static version of the manpages - - they do not get updated - -3) /pipermail/ - http://openvswitch.org/pipermail is the mailman archive. If we use github - hosting, openvswitch.org will be a CNAME for openvswitch.github.io - (or something similar). Since we do not have control over - openvswitch.github.io we cannot redirect /pipermail/* to something else. - -4) google analytics - include google analytics snippet