Re: Review Request 51128: Create Documentation Around All Options In ambari.properties

[Robert Nettleton]

---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/51128/#review145900
---


Ship it!




Ship It!

- Robert Nettleton


On Aug. 16, 2016, 4:01 a.m., Jonathan Hurley wrote:
> 
> ---
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/51128/
> ---
> 
> (Updated Aug. 16, 2016, 4:01 a.m.)
> 
> 
> Review request for Ambari, Alejandro Fernandez, Nate Cole, Robert Levas, and 
> Robert Nettleton.
> 
> 
> Bugs: AMBARI-18089
> https://issues.apache.org/jira/browse/AMBARI-18089
> 
> 
> Repository: ambari
> 
> 
> Description
> ---
> 
> Provide documentation, in markdown format, around all of Ambari's 
> configuration options. Additionally, provide a way to easily provide metadata 
> for properties that need to scale based on things like cluster size. There is 
> currently sparse to no documentation on many of these properties. For every 
> property, we need to consider things like cluster size.
> 
> The Configuration class was extended with a main() method which now takes an 
> `output=foo.md` argument to generate an MD file.
> 
> 
> Diffs
> -
> 
>   ambari-server/docs/configuration/index.md PRE-CREATION 
>   ambari-server/src/main/java/org/apache/ambari/annotations/Markdown.java 
> 0f7748e 
>   
> ambari-server/src/main/java/org/apache/ambari/server/checks/DatabaseConsistencyCheckHelper.java
>  2bebf95 
>   
> ambari-server/src/main/java/org/apache/ambari/server/configuration/Configuration.java
>  9c27e57 
>   
> ambari-server/src/main/java/org/apache/ambari/server/configuration/index_template.md
>  PRE-CREATION 
>   
> ambari-server/src/main/java/org/apache/ambari/server/controller/AmbariServer.java
>  46f6ce5 
>   
> ambari-server/src/main/java/org/apache/ambari/server/controller/utilities/DatabaseChecker.java
>  722e6f1 
>   
> ambari-server/src/test/java/org/apache/ambari/server/configuration/ConfigurationTest.java
>  22f4afa 
>   
> ambari-server/src/test/java/org/apache/ambari/server/controller/utilities/DatabaseCheckerTest.java
>  2702fdf 
>   
> ambari-server/src/test/java/org/apache/ambari/server/security/ldap/LdapPerformanceTest.java
>  dbf28be 
> 
> Diff: https://reviews.apache.org/r/51128/diff/
> 
> 
> Testing
> ---
> 
> mvn clean test
> 
> 
> Thanks,
> 
> Jonathan Hurley
> 
>

Re: Review Request 51128: Create Documentation Around All Options In ambari.properties

[Alejandro Fernandez]

> On Aug. 16, 2016, 5:20 p.m., Alejandro Fernandez wrote:
> > ambari-server/docs/configuration/index.md, line 37
> > 
> >
> > Finally, this is so useful!
> > 
> > Can this file be autogenerated?
> 
> Jonathan Hurley wrote:
> The index.md is generated from index_template.md. You would do something 
> like this:
> 
> `java org.apache.ambari.server.configuration.Configuration -output 
> ../docs/configuration/index.md`
> 
> I didn't add this to the pom.xml yet since I don't know where the project 
> is heading with documentation. I just wanted get what we have up there on 
> github.

Great, +1


- Alejandro


---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/51128/#review145882
---


On Aug. 16, 2016, 4:01 a.m., Jonathan Hurley wrote:
> 
> ---
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/51128/
> ---
> 
> (Updated Aug. 16, 2016, 4:01 a.m.)
> 
> 
> Review request for Ambari, Alejandro Fernandez, Nate Cole, Robert Levas, and 
> Robert Nettleton.
> 
> 
> Bugs: AMBARI-18089
> https://issues.apache.org/jira/browse/AMBARI-18089
> 
> 
> Repository: ambari
> 
> 
> Description
> ---
> 
> Provide documentation, in markdown format, around all of Ambari's 
> configuration options. Additionally, provide a way to easily provide metadata 
> for properties that need to scale based on things like cluster size. There is 
> currently sparse to no documentation on many of these properties. For every 
> property, we need to consider things like cluster size.
> 
> The Configuration class was extended with a main() method which now takes an 
> `output=foo.md` argument to generate an MD file.
> 
> 
> Diffs
> -
> 
>   ambari-server/docs/configuration/index.md PRE-CREATION 
>   ambari-server/src/main/java/org/apache/ambari/annotations/Markdown.java 
> 0f7748e 
>   
> ambari-server/src/main/java/org/apache/ambari/server/checks/DatabaseConsistencyCheckHelper.java
>  2bebf95 
>   
> ambari-server/src/main/java/org/apache/ambari/server/configuration/Configuration.java
>  9c27e57 
>   
> ambari-server/src/main/java/org/apache/ambari/server/configuration/index_template.md
>  PRE-CREATION 
>   
> ambari-server/src/main/java/org/apache/ambari/server/controller/AmbariServer.java
>  46f6ce5 
>   
> ambari-server/src/main/java/org/apache/ambari/server/controller/utilities/DatabaseChecker.java
>  722e6f1 
>   
> ambari-server/src/test/java/org/apache/ambari/server/configuration/ConfigurationTest.java
>  22f4afa 
>   
> ambari-server/src/test/java/org/apache/ambari/server/controller/utilities/DatabaseCheckerTest.java
>  2702fdf 
>   
> ambari-server/src/test/java/org/apache/ambari/server/security/ldap/LdapPerformanceTest.java
>  dbf28be 
> 
> Diff: https://reviews.apache.org/r/51128/diff/
> 
> 
> Testing
> ---
> 
> mvn clean test
> 
> 
> Thanks,
> 
> Jonathan Hurley
> 
>

Re: Review Request 51128: Create Documentation Around All Options In ambari.properties

[Jonathan Hurley]

> On Aug. 16, 2016, 1:20 p.m., Alejandro Fernandez wrote:
> > ambari-server/docs/configuration/index.md, line 37
> > 
> >
> > Finally, this is so useful!
> > 
> > Can this file be autogenerated?

The index.md is generated from index_template.md. You would do something like 
this:

`java org.apache.ambari.server.configuration.Configuration -output 
../docs/configuration/index.md`

I didn't add this to the pom.xml yet since I don't know where the project is 
heading with documentation. I just wanted get what we have up there on github.


- Jonathan


---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/51128/#review145882
---


On Aug. 16, 2016, 12:01 a.m., Jonathan Hurley wrote:
> 
> ---
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/51128/
> ---
> 
> (Updated Aug. 16, 2016, 12:01 a.m.)
> 
> 
> Review request for Ambari, Alejandro Fernandez, Nate Cole, Robert Levas, and 
> Robert Nettleton.
> 
> 
> Bugs: AMBARI-18089
> https://issues.apache.org/jira/browse/AMBARI-18089
> 
> 
> Repository: ambari
> 
> 
> Description
> ---
> 
> Provide documentation, in markdown format, around all of Ambari's 
> configuration options. Additionally, provide a way to easily provide metadata 
> for properties that need to scale based on things like cluster size. There is 
> currently sparse to no documentation on many of these properties. For every 
> property, we need to consider things like cluster size.
> 
> The Configuration class was extended with a main() method which now takes an 
> `output=foo.md` argument to generate an MD file.
> 
> 
> Diffs
> -
> 
>   ambari-server/docs/configuration/index.md PRE-CREATION 
>   ambari-server/src/main/java/org/apache/ambari/annotations/Markdown.java 
> 0f7748e 
>   
> ambari-server/src/main/java/org/apache/ambari/server/checks/DatabaseConsistencyCheckHelper.java
>  2bebf95 
>   
> ambari-server/src/main/java/org/apache/ambari/server/configuration/Configuration.java
>  9c27e57 
>   
> ambari-server/src/main/java/org/apache/ambari/server/configuration/index_template.md
>  PRE-CREATION 
>   
> ambari-server/src/main/java/org/apache/ambari/server/controller/AmbariServer.java
>  46f6ce5 
>   
> ambari-server/src/main/java/org/apache/ambari/server/controller/utilities/DatabaseChecker.java
>  722e6f1 
>   
> ambari-server/src/test/java/org/apache/ambari/server/configuration/ConfigurationTest.java
>  22f4afa 
>   
> ambari-server/src/test/java/org/apache/ambari/server/controller/utilities/DatabaseCheckerTest.java
>  2702fdf 
>   
> ambari-server/src/test/java/org/apache/ambari/server/security/ldap/LdapPerformanceTest.java
>  dbf28be 
> 
> Diff: https://reviews.apache.org/r/51128/diff/
> 
> 
> Testing
> ---
> 
> mvn clean test
> 
> 
> Thanks,
> 
> Jonathan Hurley
> 
>

Re: Review Request 51128: Create Documentation Around All Options In ambari.properties

[Alejandro Fernandez]

---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/51128/#review145882
---




ambari-server/docs/configuration/index.md (line 37)


Finally, this is so useful!

Can this file be autogenerated?


- Alejandro Fernandez


On Aug. 16, 2016, 4:01 a.m., Jonathan Hurley wrote:
> 
> ---
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/51128/
> ---
> 
> (Updated Aug. 16, 2016, 4:01 a.m.)
> 
> 
> Review request for Ambari, Alejandro Fernandez, Nate Cole, Robert Levas, and 
> Robert Nettleton.
> 
> 
> Bugs: AMBARI-18089
> https://issues.apache.org/jira/browse/AMBARI-18089
> 
> 
> Repository: ambari
> 
> 
> Description
> ---
> 
> Provide documentation, in markdown format, around all of Ambari's 
> configuration options. Additionally, provide a way to easily provide metadata 
> for properties that need to scale based on things like cluster size. There is 
> currently sparse to no documentation on many of these properties. For every 
> property, we need to consider things like cluster size.
> 
> The Configuration class was extended with a main() method which now takes an 
> `output=foo.md` argument to generate an MD file.
> 
> 
> Diffs
> -
> 
>   ambari-server/docs/configuration/index.md PRE-CREATION 
>   ambari-server/src/main/java/org/apache/ambari/annotations/Markdown.java 
> 0f7748e 
>   
> ambari-server/src/main/java/org/apache/ambari/server/checks/DatabaseConsistencyCheckHelper.java
>  2bebf95 
>   
> ambari-server/src/main/java/org/apache/ambari/server/configuration/Configuration.java
>  9c27e57 
>   
> ambari-server/src/main/java/org/apache/ambari/server/configuration/index_template.md
>  PRE-CREATION 
>   
> ambari-server/src/main/java/org/apache/ambari/server/controller/AmbariServer.java
>  46f6ce5 
>   
> ambari-server/src/main/java/org/apache/ambari/server/controller/utilities/DatabaseChecker.java
>  722e6f1 
>   
> ambari-server/src/test/java/org/apache/ambari/server/configuration/ConfigurationTest.java
>  22f4afa 
>   
> ambari-server/src/test/java/org/apache/ambari/server/controller/utilities/DatabaseCheckerTest.java
>  2702fdf 
>   
> ambari-server/src/test/java/org/apache/ambari/server/security/ldap/LdapPerformanceTest.java
>  dbf28be 
> 
> Diff: https://reviews.apache.org/r/51128/diff/
> 
> 
> Testing
> ---
> 
> mvn clean test
> 
> 
> Thanks,
> 
> Jonathan Hurley
> 
>

Re: Review Request 51128: Create Documentation Around All Options In ambari.properties

[Jonathan Hurley]

---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/51128/#review145835
---




ambari-server/src/main/java/org/apache/ambari/server/configuration/Configuration.java
 (lines 417 - 422)


An example of a configuration property with the new Markdown annotation.



ambari-server/src/main/java/org/apache/ambari/server/configuration/Configuration.java
 (lines 1822 - 1831)


For properties which might need more complex markdown created, we have a 
custom annotation just for configuration properties which contain things like 
recommended values based on cluster size.



ambari-server/src/main/java/org/apache/ambari/server/configuration/Configuration.java
 (line 4644)


The main() method was changed to take a template MD file and create an MD 
file which can be checked into source (index.md).

I thought about using Apache Velocity for this, but unfortunately, Markdown 
and velocity have syntax compatibility problems; it was easier to just do a 
simple string replace on a token.


- Jonathan Hurley


On Aug. 16, 2016, 12:01 a.m., Jonathan Hurley wrote:
> 
> ---
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/51128/
> ---
> 
> (Updated Aug. 16, 2016, 12:01 a.m.)
> 
> 
> Review request for Ambari, Alejandro Fernandez, Nate Cole, Robert Levas, and 
> Robert Nettleton.
> 
> 
> Bugs: AMBARI-18089
> https://issues.apache.org/jira/browse/AMBARI-18089
> 
> 
> Repository: ambari
> 
> 
> Description
> ---
> 
> Provide documentation, in markdown format, around all of Ambari's 
> configuration options. Additionally, provide a way to easily provide metadata 
> for properties that need to scale based on things like cluster size. There is 
> currently sparse to no documentation on many of these properties. For every 
> property, we need to consider things like cluster size.
> 
> The Configuration class was extended with a main() method which now takes an 
> `output=foo.md` argument to generate an MD file.
> 
> 
> Diffs
> -
> 
>   ambari-server/docs/configuration/index.md PRE-CREATION 
>   ambari-server/src/main/java/org/apache/ambari/annotations/Markdown.java 
> 0f7748e 
>   
> ambari-server/src/main/java/org/apache/ambari/server/checks/DatabaseConsistencyCheckHelper.java
>  2bebf95 
>   
> ambari-server/src/main/java/org/apache/ambari/server/configuration/Configuration.java
>  9c27e57 
>   
> ambari-server/src/main/java/org/apache/ambari/server/configuration/index_template.md
>  PRE-CREATION 
>   
> ambari-server/src/main/java/org/apache/ambari/server/controller/AmbariServer.java
>  46f6ce5 
>   
> ambari-server/src/main/java/org/apache/ambari/server/controller/utilities/DatabaseChecker.java
>  722e6f1 
>   
> ambari-server/src/test/java/org/apache/ambari/server/configuration/ConfigurationTest.java
>  22f4afa 
>   
> ambari-server/src/test/java/org/apache/ambari/server/controller/utilities/DatabaseCheckerTest.java
>  2702fdf 
>   
> ambari-server/src/test/java/org/apache/ambari/server/security/ldap/LdapPerformanceTest.java
>  dbf28be 
> 
> Diff: https://reviews.apache.org/r/51128/diff/
> 
> 
> Testing
> ---
> 
> mvn clean test
> 
> 
> Thanks,
> 
> Jonathan Hurley
> 
>

Review Request 51128: Create Documentation Around All Options In ambari.properties

[Jonathan Hurley]

---
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/51128/
---

Review request for Ambari, Alejandro Fernandez, Nate Cole, Robert Levas, and 
Robert Nettleton.


Bugs: AMBARI-18089
https://issues.apache.org/jira/browse/AMBARI-18089


Repository: ambari


Description
---

Provide documentation, in markdown format, around all of Ambari's configuration 
options. Additionally, provide a way to easily provide metadata for properties 
that need to scale based on things like cluster size. There is currently sparse 
to no documentation on many of these properties. For every property, we need to 
consider things like cluster size.

The Configuration class was extended with a main() method which now takes an 
`output=foo.md` argument to generate an MD file.


Diffs
-

  ambari-server/docs/configuration/index.md PRE-CREATION 
  ambari-server/src/main/java/org/apache/ambari/annotations/Markdown.java 
0f7748e 
  
ambari-server/src/main/java/org/apache/ambari/server/checks/DatabaseConsistencyCheckHelper.java
 2bebf95 
  
ambari-server/src/main/java/org/apache/ambari/server/configuration/Configuration.java
 9c27e57 
  
ambari-server/src/main/java/org/apache/ambari/server/configuration/index_template.md
 PRE-CREATION 
  
ambari-server/src/main/java/org/apache/ambari/server/controller/AmbariServer.java
 46f6ce5 
  
ambari-server/src/main/java/org/apache/ambari/server/controller/utilities/DatabaseChecker.java
 722e6f1 
  
ambari-server/src/test/java/org/apache/ambari/server/configuration/ConfigurationTest.java
 22f4afa 
  
ambari-server/src/test/java/org/apache/ambari/server/controller/utilities/DatabaseCheckerTest.java
 2702fdf 
  
ambari-server/src/test/java/org/apache/ambari/server/security/ldap/LdapPerformanceTest.java
 dbf28be 

Diff: https://reviews.apache.org/r/51128/diff/


Testing
---

mvn clean test


Thanks,

Jonathan Hurley