cleanup: new project docs fix-ups #11229

thaJeztah · 2015-03-07T14:13:35Z

This cleans up the recently added project docs and fixes some minor issues.

remove inline styles where possible
add redirects for renamed/replaced documents
add styles for GitHub labels to match the style on GitHub
fix minor markdown issues causing some code-blocks to be shown as text
wrap the documents to 80-chars
use 4 spaces in stead of tabs for identing and remove
trailing whitespace/redundant blank lines
optimized 'gordon' image

Screenshots of the "labels" (before/after):

thaJeztah · 2015-03-07T14:16:11Z

docs/s3_website.json

@@ -36,7 +36,10 @@
    { "Condition": { "KeyPrefixEquals": "examples/using_supervisord/" }, "Redirect": { "HostName": "$BUCKET", "ReplaceKeyPrefixWith": "articles/using_supervisord/" } },
    { "Condition": { "KeyPrefixEquals": "reference/api/registry_index_spec/" }, "Redirect": { "HostName": "$BUCKET", "ReplaceKeyPrefixWith": "reference/api/hub_registry_spec/" } },
    { "Condition": { "KeyPrefixEquals": "use/" }, "Redirect": { "HostName": "$BUCKET", "ReplaceKeyPrefixWith": "examples/" } },
-    { "Condition": { "KeyPrefixEquals": "installation/openSUSE/" }, "Redirect": { "HostName": "$BUCKET", "ReplaceKeyPrefixWith": "installation/SUSE/" } }
+    { "Condition": { "KeyPrefixEquals": "installation/openSUSE/" }, "Redirect": { "HostName": "$BUCKET", "ReplaceKeyPrefixWith": "installation/SUSE/" } },


I initially also added the line below, but wasn't sure if that would redirect everything below "/contributing" to "/project";

{ "Condition": { "KeyPrefixEquals": "contributing/" }, "Redirect": { "HostName": "$BUCKET", "ReplaceKeyPrefixWith": "project/" } },

thaJeztah · 2015-03-07T14:17:40Z

ping @moxiegirl @SvenDowideit (for redirects)

Don't be shocked by the large number of changed lines, it's mostly due to formatting and whitespace/wrapping and tabs -> spaces.

thaJeztah · 2015-03-07T14:32:58Z

Note: I just noticed that the docs-base is not automatically updated. I suspect docs make doesn't always pull the latest image, causing my changes to the CSS to not be in the current documentation on the website.

I'll create a separate ticket for that.

moxiegirl · 2015-03-07T14:33:38Z

docs/sources/project/advanced-contributing.md

+    This is a Markdown file that describes your idea. Your proposal
+    should include information like:
+
+    * Why is this changed needed or what are the use cases?


There is a line introduced in the list. Also, the terminating sentence is part of the numbered list not the bulleted list.

hmf. will update, thanks!

moxiegirl · 2015-03-07T14:49:33Z

docs/sources/project/get-help.md

+        So, it is a rich chat protocol but it can overwhelm new users. You can search
+        <a href="https://botbot.me/freenode/docker/#" target="_blank">our chat archives</a>.
+      </p>
+      Read our <a href="#irc-quickstart">IRC quickstart guide</a> below for 


Can you remove the link you added? I design linking. In instructions, too many links are distracting and they redirect the reader's focus. When I do provide links in the body of instructions, I specify a target attribute so out links open in a new tab rather than overwriting. You'll note all the outlinks open tabs.

In this case, I didn't provide the link to the instructions because they could scroll down --- and I want them too.

Sorry, will remove. Forgot I added that in the process, I stand corrected

thaJeztah · 2015-03-07T14:50:36Z

@moxiegirl the bullet-lists should be fixed now (some stray spaces). I updated the PR, but check if you have time.

Unfortunately, due to #11230, I agree that merge should be held until we know the CSS is updated. I can temporarily add the styles in a <style> tag if you want this merged before that.

moxiegirl · 2015-03-07T14:51:10Z

docs/sources/project/get-help.md


 1. In your browser open <a href="http://webchat.freenode.net" target="_blank">http://webchat.freenode.net</a>

-	![Login screen](/project/images/irc_connect.png)
+    ![Login screen](/project/images/irc_connect.png)


It makes me nervous not to see my images resolving in the preview. I trust you ran make docs before you submitted right? :-D

I think that's a GitHub weirdness. I just ran/started make docs; you can see it here http://docs.dockr.nl:8000/project/get-help/ (might be offline later :D)

This cleans up the recently added project docs and fixes some minor issues. - remove inline styles where possible - add redirects for renamed/replaced documents - add styles for GitHub labels to match the style on GitHub - fix minor markdown issues causing some code-blocks to be shown as text - wrap the documents to 80-chars - use 4 spaces in stead of tabs for identing and remove trailing whitespace/redundant blank lines - optimized 'gordon' image Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

moxiegirl · 2015-03-07T15:16:50Z

Great stuff @thaJeztah --- I need to get a primer on why I'm getting all these spacing issues. I have all my margins set to 0 and was wrapping religously --- so obviously I missed a setting on spaces or something. I'm gonna go off for a bit and then I'll come back and see where we are at re the CSS on the tables. I'd like to get both your CSS fix and this pulled today.

thaJeztah · 2015-03-07T15:21:27Z

@moxiegirl If the CSS is corrected, are you okay with removing your inline styles, or do you want me to restore them? You can see what it will look like at the http://docs.dockr.nl:8000/project/make-a-contribution/. If not, I'm happy to restore the styling later on.

Sorry for some of the slip-ups I made (all with good intent).

I'll be off for a couple of hours as well, but will check later on.

moxiegirl · 2015-03-07T17:14:05Z

@thaJeztah If the CSS is corrected, I'm defnitely okay with removing the inline styles. Don't remove 'em yet --- I'm hoping we can sort out the merge issues and all today.

No need to apologize. I really appreciate your keen eye and your expertise!

ahmetb · 2015-03-07T19:09:06Z

@thaJeztah you rock.

thaJeztah · 2015-03-07T23:12:43Z

(Thanks, Ahmet!)

@moxiegirl I've taken an unorthodox approach and created a second, alternative PR #11231 that re-introduces some inline styles

It's now midnight here, and in case you want to have something merged today, the other PR should allow you to merge even if the docs/base issue isn't fixed.

diff between this and the other PR (couldn't find how to show that with GitHub), is here:
https://gist.github.com/thaJeztah/89594c820fa6aa092379

tiborvass · 2015-03-07T23:14:28Z

@jfrazelle is there a problem with waffle.io ? It didn't label this with 0-triage. Maybe we should remove waffle completely :) That way we can remove the 0-triage label altogether.

moxiegirl · 2015-03-08T01:41:10Z

It is 5:30 here @thaJeztah I'm just taking a look at this again to see if I can merge this.

thaJeztah · 2015-03-08T10:38:54Z

@moxiegirl oh goodness, early rising!

Closing this PR because #11231 was merged. Will create a follow up PR to remove the temporary styles once the issue with docs/base is resolved.

Some inline `<style>` tags were temporarily added to the documentation because the documentation-stylesheets where not yet updated to the latest version (see moby#11231 and moby#11229 (comment)). This removes those temporary `<style>` tags. depends on moby#11230 (moby#11230) Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

thaJeztah reviewed Mar 7, 2015
View reviewed changes

moxiegirl reviewed Mar 7, 2015
View reviewed changes

thaJeztah force-pushed the Docs-contribute-to-project-fixups branch from 806edf6 to adbb9db Compare March 7, 2015 14:48

moxiegirl reviewed Mar 7, 2015
View reviewed changes

thaJeztah force-pushed the Docs-contribute-to-project-fixups branch from adbb9db to a669f5e Compare March 7, 2015 15:22

thaJeztah mentioned this pull request Mar 7, 2015

Cleanup: new project docs fix-ups (alternative) #11231

Merged

tiborvass added the status/3-docs-review label Mar 7, 2015

thaJeztah closed this Mar 8, 2015

dmp42 removed the status/3-docs-review label Mar 8, 2015

thaJeztah mentioned this pull request Mar 8, 2015

cleanup: docs: remove temporary inline styles #11237

Merged

thaJeztah deleted the Docs-contribute-to-project-fixups branch April 29, 2016 14:41

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

cleanup: new project docs fix-ups #11229

cleanup: new project docs fix-ups #11229

thaJeztah commented Mar 7, 2015

thaJeztah Mar 7, 2015

thaJeztah commented Mar 7, 2015

thaJeztah commented Mar 7, 2015

moxiegirl Mar 7, 2015

thaJeztah Mar 7, 2015

moxiegirl Mar 7, 2015

thaJeztah Mar 7, 2015

thaJeztah commented Mar 7, 2015

moxiegirl Mar 7, 2015

thaJeztah Mar 7, 2015

moxiegirl commented Mar 7, 2015

thaJeztah commented Mar 7, 2015

moxiegirl commented Mar 7, 2015

ahmetb commented Mar 7, 2015

thaJeztah commented Mar 7, 2015

tiborvass commented Mar 7, 2015

moxiegirl commented Mar 8, 2015

thaJeztah commented Mar 8, 2015

cleanup: new project docs fix-ups #11229

cleanup: new project docs fix-ups #11229

Conversation

thaJeztah commented Mar 7, 2015

thaJeztah Mar 7, 2015

Choose a reason for hiding this comment

thaJeztah commented Mar 7, 2015

thaJeztah commented Mar 7, 2015

moxiegirl Mar 7, 2015

Choose a reason for hiding this comment

thaJeztah Mar 7, 2015

Choose a reason for hiding this comment

moxiegirl Mar 7, 2015

Choose a reason for hiding this comment

thaJeztah Mar 7, 2015

Choose a reason for hiding this comment

thaJeztah commented Mar 7, 2015

moxiegirl Mar 7, 2015

Choose a reason for hiding this comment

thaJeztah Mar 7, 2015

Choose a reason for hiding this comment

moxiegirl commented Mar 7, 2015

thaJeztah commented Mar 7, 2015

moxiegirl commented Mar 7, 2015

ahmetb commented Mar 7, 2015

thaJeztah commented Mar 7, 2015

tiborvass commented Mar 7, 2015

moxiegirl commented Mar 8, 2015

thaJeztah commented Mar 8, 2015