You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ad...@apache.org on 2016/06/17 23:39:45 UTC
[60/63] [abbrv] incubator-mynewt-site git commit: final fix for site
-> docs links
final fix for site -> docs links
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/2fd75093
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/2fd75093
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/2fd75093
Branch: refs/heads/develop
Commit: 2fd75093ed6dc754b283d1bfbfeac2127e26f012
Parents: ed8632f
Author: Gavin Jefferies <ga...@runtime.io>
Authored: Fri Jun 17 12:37:24 2016 -0700
Committer: Gavin Jefferies <ga...@runtime.io>
Committed: Fri Jun 17 14:09:08 2016 -0700
----------------------------------------------------------------------
README.md | 10 +++++---
build.py | 41 +++++++++++++++++++++++--------
custom-theme/about.html | 15 +++++------
custom-theme/choose_doc_version.html | 8 ++++++
custom-theme/community.html | 12 +++++----
custom-theme/content.html | 9 -------
custom-theme/download.html | 3 +--
custom-theme/events.html | 4 +--
custom-theme/fix_up_content.html | 1 +
custom-theme/landing.html | 2 +-
custom-theme/manual_links.html | 10 --------
custom-theme/nav.html | 2 +-
custom-theme/news.html | 13 ----------
custom-theme/quick-start.html | 2 +-
docs/about.md | 2 +-
docs/download.md | 4 +--
docs/quick-start.md | 12 ++++-----
mkdocs.yml | 2 +-
18 files changed, 76 insertions(+), 76 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/2fd75093/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index 7d22a84..214108f 100644
--- a/README.md
+++ b/README.md
@@ -2,9 +2,9 @@ The Apache MyNewt site is built using [MkDocs](http://www.mkdocs.org/).
## Setup
### For all contributors:
-* Install MkDocs on your system.
+* Install [MkDocs](http://www.mkdocs.org/) on your system.
-### Additionally for mynewt-site committers:
+### Additionally for committers:
* `pip install GitPython`
* `pip install sh`
@@ -18,7 +18,7 @@ The Apache MyNewt site is built using [MkDocs](http://www.mkdocs.org/).
1. Submit a pull request.
## Releasing a versioned set of MyNewt documentation
-When a new release of MyNewt occurs, the git `develop` branch of this repository should be in sync with that released version.
+When a new release of MyNewt OS and its associated tools occurs, the documentation in the git `develop` branch of this repository should be in sync with the released version. The following steps will create a documentation branch for the release and make it available as the default documentation from the mynewt-site.
### Build
1. Merge `develop` to `master`.
@@ -39,3 +39,7 @@ When a new release of MyNewt occurs, the git `develop` branch of this repository
1. Run: `./deploy.sh`
1. This will leave you on the `asf-site` branch.
1. Commit & push the changes.
+
+## Links to Documentation
+
+For the deployed site a version prefix is added to the URL for each mkdocs page. When developing there is no version prefix. If you want to link from a _site page_ to a _documentation page_ you should prefix the URL with */DOCSLINK/* so that the user is taken to the correct location when browsing in production.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/2fd75093/build.py
----------------------------------------------------------------------
diff --git a/build.py b/build.py
index e0c4414..9957f20 100755
--- a/build.py
+++ b/build.py
@@ -5,18 +5,18 @@ import click
import sh
from git import Repo, Git
from mkdocs import config
+import fileinput
@click.command()
@click.option('-s', '--site-branch', default='master', help='Use this branch as source for the top level pages')
-@click.option('--dirty', default=False, is_flag=True, help='Allow outstanding modifications in the working directory')
-def build(site_branch, dirty):
+def build(site_branch):
# make sure there are no local mods outstanding
repo = Repo(os.getcwd())
- if not dirty and (repo.is_dirty() or repo.untracked_files):
+ if repo.is_dirty() or repo.untracked_files:
print "ERROR: Your working directory has outstanding changes."
- print "If you are sure this is ok run again with --dirty."
+ print "Commit or stash them."
return
mygit = Git(os.getcwd())
@@ -40,16 +40,37 @@ def build(site_branch, dirty):
return
mygit.checkout(site_branch)
- print "Building the top level site pages (from %s)..." % (site_branch)
+ print "Building site pages from: %s..." % (site_branch)
sh.mkdocs('build', '--clean')
for version in cfg['extra']['versions']:
mygit.checkout(version['branch'])
- print 'Building docs for: %s...' % (version['branch'])
- sh.mkdocs('build', '--site-dir', 'site/%s' % (version['branch']))
- if version['latest']:
- print 'Building latest...'
- sh.mkdocs('build', '--site-dir', 'site/latest')
+ deployVersion(version)
+
+def deployVersion(version):
+ mygit.checkout(version['branch'])
+ buildTo(version['branch'])
+ if version['latest']:
+ buildTo('latest')
+
+def buildTo(branch):
+ print 'Building doc pages for: %s...' % (branch)
+ branchCfg = config.load_config()
+ if branchCfg['extra']['version'] != branch:
+ updateConfigVersion(branch)
+ sh.mkdocs('build', '--site-dir', 'site/%s' % (branch))
+ if branchCfg['extra']['version'] != branch:
+ sh.git('checkout', '--', 'mkdocs.yml')
+
+def updateConfigVersion(branch):
+ updated = False
+ for line in fileinput.input('mkdocs.yml', inplace=True):
+ line = line.rstrip()
+ if line.find(" version:") == 0:
+ line = " version: '%s'" % (branch)
+ updated = True
+ print line
+ assert updated, "Could not fix the version field on %s" % (branch)
if __name__ == '__main__':
repo = Repo(os.getcwd())
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/2fd75093/custom-theme/about.html
----------------------------------------------------------------------
diff --git a/custom-theme/about.html b/custom-theme/about.html
index 471a5be..47a6fd0 100644
--- a/custom-theme/about.html
+++ b/custom-theme/about.html
@@ -17,17 +17,17 @@
Board Support Infrastructure
</li>
<li>
- System level logs and statistics
+ System level logs and statistics
</li>
<li>
Signed images and remote firmware upgrade
</li>
<li>
Bluetooth Low Energy stack (BLE 4.2)
- </li>
- <br>
- <p> For features in each release, see <a href="https://cwiki.apache.org/confluence/display/MYNEWT/Apache+Mynewt+Project"> Release Notes </a>
- </p>
+ </li>
+ <br>
+ <p> For features in each release, see <a href="https://cwiki.apache.org/confluence/display/MYNEWT/Apache+Mynewt+Project"> Release Notes </a>
+ </p>
</div>
<div class="col-md-4">
<h3> Source Code on github.com </h3>
@@ -48,11 +48,8 @@
<div class="row">
<div class="col-md-12 content">
{% block content %}
- {{ content }}
+ {% include 'fix_up_content.html' %}
{% endblock %}
</div>
</div>
</div>
-
-
-
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/2fd75093/custom-theme/choose_doc_version.html
----------------------------------------------------------------------
diff --git a/custom-theme/choose_doc_version.html b/custom-theme/choose_doc_version.html
index 67f857f..5c408e0 100644
--- a/custom-theme/choose_doc_version.html
+++ b/custom-theme/choose_doc_version.html
@@ -1,3 +1,10 @@
+{% if config.extra.version == 'none' %}
+<select class="form-control">
+<option>
+ developing
+</option>
+</select>
+{% else %}
<select class="form-control" onchange="if (this.value) window.location.href=this.value">
{% for version in config.extra.versions %}
<option
@@ -8,3 +15,4 @@
</option>
{% endfor %}
</select>
+{% endif %}
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/2fd75093/custom-theme/community.html
----------------------------------------------------------------------
diff --git a/custom-theme/community.html b/custom-theme/community.html
index 06616c1..f9319bc 100644
--- a/custom-theme/community.html
+++ b/custom-theme/community.html
@@ -4,7 +4,9 @@
<div class="container small-no-padding">
<div class="row content">
<div class="col-md-12">
- {% block content %} {{ content }} {% endblock %}
+ {% block content %}
+ {% include 'fix_up_content.html' %}
+ {% endblock %}
</div>
</div>
<div class="row">
@@ -64,7 +66,7 @@
<p> If you are a contributor and wish to work on a change, open a JIRA ticket first. It's always a good idea to introduce the change in the dev@ mailing list and refer to that ticket. When you generate a pull request into the github mirror for your change, always reference the JIRA ticket number in the title. JIRA is set up to resolve the ticket when your code is merged into the ASF git repository and the pull request closed. </p>
<h3>Contributing Code</h3>
- <p>
+ <p>
You can start contributing right away, even if you are not a committer on Apache Mynewt! One requirement is that you adhere to the Apache's proposed workflow as explained <a href="https://git-wip-us.apache.org/docs/workflow.html">here</a>. Basically, you submit your initial edits for your peers to review and merge. After a few successful patches under your belt, you will get access to commit code directly to the module you are working on in the repository. And over time, you will get full access to all the repositories, where you can commit code to any module. </p>
<p>You may choose to submit patches in one of the two following ways:
<br>
@@ -82,17 +84,17 @@
</ul>
<p>In the comment for the pull request, include a description of the changes you have made and why. Github will automatically notify everyone on the commits@mynewt.incubator.apache.org mailing list about the newly opened pull requests. You can open a pull request even if you don't think the code is ready for merging but want some discussion on the matter. </p>
<p> Upon receiving notification, one or more committers will review your work, ask for edits or clarifications, and merge when your proposed changes are ready.</p>
- </li>
+ </li>
<li>
Use the `git format-patch` command to produce a patch file. Submit the patch (your code changes along with a diff from the old code) via email to the @dev mailing list. Summarize the issue and your work in the email. Regular project members will review your suggested patch and add it to the repository, acknowledging your contribution by referencing your name in the commit message. </li>
</ol>
</p>
-
+
<h3>Contributing to the web site</h3>
<p> Go to <a href="https://github.com/apache/incubator-mynewt-site">Apache Mynewt documentation repo mirrored on github</a> to clone the repository into a local branch on your machine. Make your changes. Then submit a pull request on the github mirror repository by clicking the green "New pull request" button on the page. </p>
<p> To know more check out the <a href="http://mynewt.apache.org/faq/how_to_edit_docs/"> Appendix </a>. </p>
<br>
-
+
</div>
</div>
</div>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/2fd75093/custom-theme/content.html
----------------------------------------------------------------------
diff --git a/custom-theme/content.html b/custom-theme/content.html
deleted file mode 100644
index b578f1a..0000000
--- a/custom-theme/content.html
+++ /dev/null
@@ -1,9 +0,0 @@
-{% if meta.source %}
- <div class="source-links">
- {% for filename in meta.source %}
- <span class="label label-primary">{{ filename }}</span>
- {% endfor %}
- </div>
-{% endif %}
-
-{{ content }}
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/2fd75093/custom-theme/download.html
----------------------------------------------------------------------
diff --git a/custom-theme/download.html b/custom-theme/download.html
index 58caa97..741670f 100644
--- a/custom-theme/download.html
+++ b/custom-theme/download.html
@@ -1,11 +1,10 @@
{% include 'secondary-banner.html' %}
-
<div class="container">
<div class="row">
<div class="col-md-12">
{% block content %}
- {{ content }}
+ {% include 'fix_up_content.html' %}
{% endblock %}
</div>
</div>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/2fd75093/custom-theme/events.html
----------------------------------------------------------------------
diff --git a/custom-theme/events.html b/custom-theme/events.html
index f8d77c8..e5ec226 100644
--- a/custom-theme/events.html
+++ b/custom-theme/events.html
@@ -5,7 +5,7 @@
<div class="row">
<div class="col-md-12 content">
{% block content %}
- {{ content }}
+ {% include 'fix_up_content.html' %}
{% endblock %}
{% for event in config.extra.events %}
<div class="event">
@@ -19,4 +19,4 @@
</div>
</div>
</div>
-</div>
\ No newline at end of file
+</div>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/2fd75093/custom-theme/fix_up_content.html
----------------------------------------------------------------------
diff --git a/custom-theme/fix_up_content.html b/custom-theme/fix_up_content.html
new file mode 100644
index 0000000..177cdca
--- /dev/null
+++ b/custom-theme/fix_up_content.html
@@ -0,0 +1 @@
+{% if config.extra.version == 'none' %}{{ content|replace("/DOCSLINK/", "/") }}{% else %}{{ content|replace("/DOCSLINK/", "/latest/") }}{% endif %}
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/2fd75093/custom-theme/landing.html
----------------------------------------------------------------------
diff --git a/custom-theme/landing.html b/custom-theme/landing.html
index 25b37ec..cb3dcab 100644
--- a/custom-theme/landing.html
+++ b/custom-theme/landing.html
@@ -5,7 +5,7 @@
<div class="row tagline">
<div class="col-md-12 text-center">
<p>
- {{ content }}
+ {% include 'fix_up_content.html' %}
</p>
</div>
</div>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/2fd75093/custom-theme/manual_links.html
----------------------------------------------------------------------
diff --git a/custom-theme/manual_links.html b/custom-theme/manual_links.html
deleted file mode 100644
index b4615f6..0000000
--- a/custom-theme/manual_links.html
+++ /dev/null
@@ -1,10 +0,0 @@
-
-<ul class="nav nav-pills">
- {% set man_titles=['Mynewt OS Manual', 'Newt Manager Manual', 'Newt Tool Manual'] %}
- {% set man_desc={'Mynewt OS Manual': 'Mynewt OS', 'Newt Manager Manual': 'Newt Mgr', 'Newt Tool Manual': 'Newt Tool'} %}
- {% for nav_item in nav %}
- {% if nav_item.title in man_titles %}
- <li {% if nav_item.active %}class="active"{% endif %} role="presentation"><a href="{{ nav_item.children[0].url }}">{{ man_desc[nav_item.title] }}</a></li>
- {% endif %}
- {% endfor %}
-</ul>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/2fd75093/custom-theme/nav.html
----------------------------------------------------------------------
diff --git a/custom-theme/nav.html b/custom-theme/nav.html
index adfd702..0373a02 100644
--- a/custom-theme/nav.html
+++ b/custom-theme/nav.html
@@ -37,7 +37,7 @@
<a href="/about/">About</a>
</li>
<li {{ docs_are_active(current_page) }}>
- <a href="/{{ config.extra.version }}/{{ config.extra.doc_path }}">Documentation</a>
+ <a href="{% if config.extra.version != 'none' %}/{{ config.extra.version }}{% endif %}/{{ config.extra.doc_path }}">Documentation</a>
</li>
<li {{ active_nav(current_page, 'Download') }}>
<a href="/download/">Download</a>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/2fd75093/custom-theme/news.html
----------------------------------------------------------------------
diff --git a/custom-theme/news.html b/custom-theme/news.html
deleted file mode 100644
index 57e8d37..0000000
--- a/custom-theme/news.html
+++ /dev/null
@@ -1,13 +0,0 @@
-{% include 'main-banner.html' %}
-
-
-<div class="container">
-<div class="row">
- <div class="col-md-12">
- <h2>News about Apache Mynewt</h2>
- <p>Apache Mynewt is still a podling in incubation.</p>
- <br>
-
- </div>
-</div>
-</div>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/2fd75093/custom-theme/quick-start.html
----------------------------------------------------------------------
diff --git a/custom-theme/quick-start.html b/custom-theme/quick-start.html
index aa9748b..9c58658 100644
--- a/custom-theme/quick-start.html
+++ b/custom-theme/quick-start.html
@@ -6,7 +6,7 @@
<div class="row">
<div class="col-md-12 content">
{% block content %}
- {{ content }}
+ {% include 'fix_up_content.html' %}
{% endblock %}
</div>
</div>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/2fd75093/docs/about.md
----------------------------------------------------------------------
diff --git a/docs/about.md b/docs/about.md
index abc194c..16ef027 100644
--- a/docs/about.md
+++ b/docs/about.md
@@ -35,4 +35,4 @@ If you have suggestions for a new feature, use case, or implementation improveme
###FAQ
-<font color="#F2853F"> Questions? </font> Click [here](http://mynewt.apache.org/latest/faq/answers)
+<font color="#F2853F"> Questions? </font> Click [here](/DOCSLINK/faq/answers)
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/2fd75093/docs/download.md
----------------------------------------------------------------------
diff --git a/docs/download.md b/docs/download.md
index e0aa268..a3aff51 100644
--- a/docs/download.md
+++ b/docs/download.md
@@ -7,9 +7,9 @@
#### Fresh install
-If you are brand new to Mynewt, go to [Quick Start](http://mynewt.apache.org/latest/os/get_started/get_started/). The Newt tool will automatically download the latest release.
+If you are brand new to Mynewt, go to [Quick Start](/DOCSLINK/os/get_started/get_started/). The Newt tool will automatically download the latest release.
-If you have already installed the Newt tool but not started any project yet, go to [Create Your First Project](http://mynewt.apache.org/latest/os/get_started/project_create/). The Newt tool will automatically download the latest release.
+If you have already installed the Newt tool but not started any project yet, go to [Create Your First Project](/DOCSLINK/os/get_started/project_create/). The Newt tool will automatically download the latest release.
#### Upgrade
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/2fd75093/docs/quick-start.md
----------------------------------------------------------------------
diff --git a/docs/quick-start.md b/docs/quick-start.md
index 492b1dc..002c487 100644
--- a/docs/quick-start.md
+++ b/docs/quick-start.md
@@ -4,26 +4,26 @@ Apache Mynewt currently offers two ways to quickly get set up, each appealing to
<br>
-* **Option 1:** All-in-one docker container that bundles Newt tool, developer toolchains and libraries. For this option, go to [Docker instructions](http://mynewt.apache.org/latest/os/get_started/docker/)
+* **Option 1:** All-in-one docker container that bundles Newt tool, developer toolchains and libraries. For this option, go to [Docker instructions](/DOCSLINK/os/get_started/docker/)
-* **Option 2:** Step-by-step instructions to install the Newt tool, developer toolchains and libraries natively on your computer. For this option, go to [Native Setup](http://mynewt.apache.org/latest/os/get_started/native_tools/)
+* **Option 2:** Step-by-step instructions to install the Newt tool, developer toolchains and libraries natively on your computer. For this option, go to [Native Setup](/DOCSLINK/os/get_started/native_tools/)
<br>
### Go!
-Start a new project as explained under [Create Your First Project](http://mynewt.apache.org/latest/os/get_started/project_create/). The core Mynewt OS is automatically downloaded as part of the project installation.
+Start a new project as explained under [Create Your First Project](/DOCSLINK/os/get_started/project_create/). The core Mynewt OS is automatically downloaded as part of the project installation.
<br>
-* When you [Create Your First Project](http://mynewt.apache.org/latest/os/get_started/project_create/) you define a simulated target and run Project Blinky, the Hello World equivalent in the embedded world.
+* When you [Create Your First Project](/DOCSLINK/os/get_started/project_create/) you define a simulated target and run Project Blinky, the Hello World equivalent in the embedded world.
-* If you have one of the supported [boards](../), you can make real LEDs blink in [Project Blinky](http://mynewt.apache.org/latest/os/tutorials/arduino_zero/). Simply choose the appropriate tutorial for the board and proceed.
+* If you have one of the supported [boards](../), you can make real LEDs blink in [Project Blinky](/DOCSLINK/os/tutorials/arduino_zero/). Simply choose the appropriate tutorial for the board and proceed.
<br>
### And More...
-Explore the [Tutorials](http://mynewt.apache.org/latest/os/tutorials/tutorials/) section for other interesting projects or simply to learn more about Mynewt's capabilities and get familiar with its use.
+Explore the [Tutorials](/DOCSLINK/os/tutorials/tutorials/) section for other interesting projects or simply to learn more about Mynewt's capabilities and get familiar with its use.
<br>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/2fd75093/mkdocs.yml
----------------------------------------------------------------------
diff --git a/mkdocs.yml b/mkdocs.yml
index 0c6d58f..9146f4a 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -369,7 +369,7 @@ markdown_extensions:
pygments_style: xcode
extra:
- version: 'develop'
+ version: 'none'
versions:
- label: 'develop'
branch: 'develop'