Add framework for developer documentation #711

Merged
merged 3 commits into from Mar 1, 2017

Conversation

3 participants
@daniel-beck
Contributor

daniel-beck commented Feb 28, 2017

Well… it was time to call this one "good enough" ;-)

Initial release of the developer documentation, focusing on providing a structure and reusable elements (for content writers) and serving as a documentation hub (for developers), linking to relevant repositories and wiki pages for each topic.

Only a handful of actual documentation pages exist, and they're not the goal of this PR anyway – that's more sample content really to get the ideas about the structure across. Actual content can always be added/migrated later, in smaller followup PRs, for individual documentation sections.

To indicate the current work-in-progress state (which still is superior to e.g. Extend Jenkins IMO), includes tiny 'warning' icons in the developer documentation sidebar.

Changes beyond doc/developer/:

  • Add "guide" documentation type associated with chapters, similar to sections.
  • Add the actual page to section and chapter, as it's the most flexible way to work with one of these elements -- should probably supersede most of the simple ones, like title or summary.
  • Add a new kind of "handbook" at /doc/developer/ -- the "devbook"
  • Add a developer meta-layout, and inherit developerchapter, developerguide, and developersection from it.
  • Add reusable wip partial so we don't copy & paste that admonition to a billion pages. Should probably be adopted by the handbook.
  • Just link to 'reference documentation' in the developer section of the user documentation sidebar.

No screenshots because GitHub upload fails right now.

@daniel-beck

This comment has been minimized.

Show comment
Hide comment
@daniel-beck

daniel-beck Feb 28, 2017

Contributor

Would be great if @jglick @stephenc @oleg-nenashev @rtyler could look this over. Thanks!

Contributor

daniel-beck commented Feb 28, 2017

Would be great if @jglick @stephenc @oleg-nenashev @rtyler could look this over. Thanks!

@rtyler

This comment has been minimized.

Show comment
Hide comment
@rtyler

rtyler Feb 28, 2017

Member

Now that AWS S3 is recovering, can you publish some screenshots now?

Member

rtyler commented Feb 28, 2017

Now that AWS S3 is recovering, can you publish some screenshots now?

@rtyler

I think it's a good starting point, and don't really have any objections to merging it in its current condition

@@ -0,0 +1,5 @@
+---
+layout: developer

This comment has been minimized.

@rtyler

rtyler Feb 28, 2017

Member

Is this different from developer and developersection just to be different?

@rtyler

rtyler Feb 28, 2017

Member

Is this different from developer and developersection just to be different?

This comment has been minimized.

@daniel-beck

daniel-beck Feb 28, 2017

Contributor

I created a layout for each kind of page to prepare for future presentation differences (as today already in chapter), and to be able to see at a glance from the source what a document is used for.

developer is just the "abstract superclass" of the three developer.+ layouts.

@daniel-beck

daniel-beck Feb 28, 2017

Contributor

I created a layout for each kind of page to prepare for future presentation differences (as today already in chapter), and to be able to see at a glance from the source what a document is used for.

developer is just the "abstract superclass" of the three developer.+ layouts.

This comment has been minimized.

@rtyler

rtyler Feb 28, 2017

Member

If you're confident they're going to differ in the future then that's fine. This isn't Java so redundant "hierarchies" aren't necessary 😈

@rtyler

rtyler Feb 28, 2017

Member

If you're confident they're going to differ in the future then that's fine. This isn't Java so redundant "hierarchies" aren't necessary 😈

+
+%ol
+ - site.devbook.chapters.each do |chapter|
+ %li{:style => 'font-size: 24px;'}

This comment has been minimized.

@rtyler

rtyler Feb 28, 2017

Member

This kind of thing is better accomplished with %h3 type tags rather than inline CSS.

@rtyler

rtyler Feb 28, 2017

Member

This kind of thing is better accomplished with %h3 type tags rather than inline CSS.

+  
+ %li{:style => 'font-size: 24px;'}
+ %a{:href => 'guides'}
+ Appendix C: Index of All How-To Guides

This comment has been minimized.

@rtyler

rtyler Feb 28, 2017

Member

Above in the actual document it's titled "Appendix B", which is it?

@rtyler

rtyler Feb 28, 2017

Member

Above in the actual document it's titled "Appendix B", which is it?

This comment has been minimized.

@daniel-beck

daniel-beck Feb 28, 2017

Contributor

I haven't figured out how to make the site assign the sequence, so I'm probably just off by one.

@daniel-beck

daniel-beck Feb 28, 2017

Contributor

I haven't figured out how to make the site assign the sequence, so I'm probably just off by one.

+---
+
+////
+https://wiki.jenkins-ci.org/display/JENKINS/Jenkins+Pieces+in+GitHub

This comment has been minimized.

@rtyler

rtyler Feb 28, 2017

Member

Shouldn't this be in the references front-matter?

@rtyler

rtyler Feb 28, 2017

Member

Shouldn't this be in the references front-matter?

This comment has been minimized.

@daniel-beck

daniel-beck Mar 1, 2017

Contributor

Right, left it out because of the terrible URL, needs a different label than page title.

@daniel-beck

daniel-beck Mar 1, 2017

Contributor

Right, left it out because of the terrible URL, needs a different label than page title.

+`Messages.properties` content:
+
+[source]
+ItemGroupMixIn.may_not_copy_as_it_contains_secrets_and_=May not copy {0} as it contains secrets and {1} has {2}/{3} but not /{4}

This comment has been minimized.

@rtyler

rtyler Feb 28, 2017

Member

I think this line is supposed to be fenced with a preceding and following ----

@rtyler

rtyler Feb 28, 2017

Member

I think this line is supposed to be fenced with a preceding and following ----

This comment has been minimized.

@daniel-beck

daniel-beck Mar 1, 2017

Contributor

No difference AFAICT, but done.

@daniel-beck

daniel-beck Mar 1, 2017

Contributor

No difference AFAICT, but done.

This comment has been minimized.

@rtyler

rtyler Mar 1, 2017

Member

Understood. I view it like single line if statements in most languages. Yes they're technically legal, but they are often the source of accidental bugs and oversights that it's best to just wrap all conditionals in curly braces

@rtyler

rtyler Mar 1, 2017

Member

Understood. I view it like single line if statements in most languages. Yes they're technically legal, but they are often the source of accidental bugs and oversights that it's best to just wrap all conditionals in curly braces

@daniel-beck

This comment has been minimized.

Show comment
Hide comment
@daniel-beck

daniel-beck Feb 28, 2017

Contributor

Now that AWS S3 is recovering, can you publish some screenshots now?

Actual documentation looks like this:

screen shot

Most pages look like this (main content area):

screen shot

Contributor

daniel-beck commented Feb 28, 2017

Now that AWS S3 is recovering, can you publish some screenshots now?

Actual documentation looks like this:

screen shot

Most pages look like this (main content area):

screen shot

+
+== Request Handling
+
+Jenkins classes are bound to URLs by using http://stapler.kohsuke.org[Stapler]. The singleton +jenkinsdoc:Jenkins[]+ instance is bound to the context root (i.e. "/") URL, and the rest of the objects are bound according to their reachability from this root object. Stapler uses reflection to recursively determine how to process any given URL. A few examples of how the URL `/foo/bar` could be processed:

This comment has been minimized.

@jglick

jglick Feb 28, 2017

Contributor

Is this jenkinsdoc macro going to work for plugin classes too?

@jglick

jglick Feb 28, 2017

Contributor

Is this jenkinsdoc macro going to work for plugin classes too?

This comment has been minimized.

@daniel-beck

daniel-beck Mar 1, 2017

Contributor

Unfortunately not, only core. https://github.com/jenkins-infra/jenkins.io/blob/611c56e050accfd48319ef3b35d551b78838d561/STYLEGUIDE.adoc#javadoc-links

Can probably be added for plugins as well (but probably only in the simple javadoc/staplerdoc forms, and specifying the plugin ID. We have http://javadoc.jenkins.io/plugin/ now, after all.

@daniel-beck

daniel-beck Mar 1, 2017

Contributor

Unfortunately not, only core. https://github.com/jenkins-infra/jenkins.io/blob/611c56e050accfd48319ef3b35d551b78838d561/STYLEGUIDE.adoc#javadoc-links

Can probably be added for plugins as well (but probably only in the simple javadoc/staplerdoc forms, and specifying the plugin ID. We have http://javadoc.jenkins.io/plugin/ now, after all.

+Jenkins classes are bound to URLs by using http://stapler.kohsuke.org[Stapler]. The singleton +jenkinsdoc:Jenkins[]+ instance is bound to the context root (i.e. "/") URL, and the rest of the objects are bound according to their reachability from this root object. Stapler uses reflection to recursively determine how to process any given URL. A few examples of how the URL `/foo/bar` could be processed:
+
+* A `getFoo(String)` is defined on the `Jenkins` object, and Stapler passes `bar` as a parameter. The object returned has a method called `doIndex(…)` that gets called and renders the response.
+* `getFoo()` or `doFoo()` are defined. They return an object that has a `getBar` or `doBar` method. The object returned from that has an associated `index.jelly` or `index.groovy` view.

This comment has been minimized.

@jglick

jglick Feb 28, 2017

Contributor

No, doFoo() would be invoked as a web method, and it would have to use StaplerRequest.getRestOfPath() to do any further processing if it cared about /bar. Similarly doBar would be invoked as a web method—not returning an object for further binding.

@jglick

jglick Feb 28, 2017

Contributor

No, doFoo() would be invoked as a web method, and it would have to use StaplerRequest.getRestOfPath() to do any further processing if it cared about /bar. Similarly doBar would be invoked as a web method—not returning an object for further binding.

+
+* A `getFoo(String)` is defined on the `Jenkins` object, and Stapler passes `bar` as a parameter. The object returned has a method called `doIndex(…)` that gets called and renders the response.
+* `getFoo()` or `doFoo()` are defined. They return an object that has a `getBar` or `doBar` method. The object returned from that has an associated `index.jelly` or `index.groovy` view.
+* `getFoo()` or `doFoo()` are defined. The object return has a view named `bar.jelly` or `bar.groovy` defined.

This comment has been minimized.

@jglick

jglick Feb 28, 2017

Contributor

Again, getFoo only, not doFoo.

@jglick

jglick Feb 28, 2017

Contributor

Again, getFoo only, not doFoo.

+
+== Views
+
+Jenkins' model objects have multiple _views_ that are used to render HTML pages about each object. Views are written in http://jakarta.apache.org/commons/jelly/[Jelly] or http://groovy-lang.org/[Groovy] and can be composed of a number of different partial views (or view fragments).

This comment has been minimized.

@jglick

jglick Feb 28, 2017

Contributor

@jglick

jglick Feb 28, 2017

Contributor

This comment has been minimized.

@daniel-beck

daniel-beck Mar 1, 2017

Contributor

Ugh. I was expecting Asciidoc to take care of that. Even Markdown has SmartyPants. Very disappointing.

@daniel-beck

daniel-beck Mar 1, 2017

Contributor

Ugh. I was expecting Asciidoc to take care of that. Even Markdown has SmartyPants. Very disappointing.

+- url: https://wiki.jenkins-ci.org/display/JENKINS/Building+Jenkins
+ title: Building Jenkins
+- url: https://wiki.jenkins-ci.org/pages/viewpage.action?pageId=3309681
+ title: Why Maven?

This comment has been minimized.

@jglick

jglick Feb 28, 2017

Contributor

Ancient, probably obsolete.

@jglick

jglick Feb 28, 2017

Contributor

Ancient, probably obsolete.

This comment has been minimized.

@daniel-beck

daniel-beck Mar 1, 2017

Contributor

Well, it does explain some of why we use Maven. Until this is made part of the plugin tutorial, a reference is still useful. Of course this is the first thing to be killed of.

@daniel-beck

daniel-beck Mar 1, 2017

Contributor

Well, it does explain some of why we use Maven. Until this is made part of the plugin tutorial, a reference is still useful. Of course this is the first thing to be killed of.

+- url: https://github.com/jenkinsci/pipeline-plugin/blob/master/DEVGUIDE.md
+ title: Plugin Developer Guide
+- url: https://github.com/jenkinsci/pipeline-plugin/blob/master/COMPATIBILITY.md
+ title: Plugins Compatible with Pipeline

This comment has been minimized.

@@ -0,0 +1,29 @@
+---
+title: Writing an SCM Plugin

This comment has been minimized.

+- url: https://jenkinsci.github.io/maven-hpi-plugin/plugin-info.html
+ title: Maven HPI Plugin site
+- url: https://wiki.jenkins-ci.org/display/JENKINS/FindBugs+in+plugins
+ title: FindBugs in Plugins # TODO Is this obsolete with recent parent POM versions?

This comment has been minimized.

@jglick

jglick Feb 28, 2017

Contributor

Well, it does talk about 2.x.

@jglick

jglick Feb 28, 2017

Contributor

Well, it does talk about 2.x.

@@ -0,0 +1,20 @@
+---
+title: Plugin Tutorial

This comment has been minimized.

@jglick

jglick Feb 28, 2017

Contributor

Is there a reason this copies & pastes content/doc/developer/plugin-tutorial/index.adoc?

@jglick

jglick Feb 28, 2017

Contributor

Is there a reason this copies & pastes content/doc/developer/plugin-tutorial/index.adoc?

This comment has been minimized.

@daniel-beck

daniel-beck Mar 1, 2017

Contributor

Accidental leftover from when I cleared out half finished pages in preparation for this PR.

@daniel-beck

daniel-beck Mar 1, 2017

Contributor

Accidental leftover from when I cleared out half finished pages in preparation for this PR.

@@ -0,0 +1,20 @@
+---
+title: Plugin Tutorial

This comment has been minimized.

@jglick

jglick Feb 28, 2017

Contributor

And this?

@jglick

jglick Feb 28, 2017

Contributor

And this?

@rtyler

rtyler approved these changes Mar 1, 2017

As far as I am concerned, I think this is a great starting point and many times better than the nothing that's currently on jenkins;io 😄

@rtyler rtyler merged commit 6555f9e into jenkins-infra:master Mar 1, 2017

1 check was pending

continuous-integration/jenkins/pr-merge This commit is scheduled to be built
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment