mesos-reviews mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joseph Wu <jos...@mesosphere.io>
Subject Re: Review Request 42790: Added documentation for all http endpoints.
Date Wed, 27 Jan 2016 21:13:26 GMT


> On Jan. 26, 2016, 11:37 a.m., Joseph Wu wrote:
> > Instead of committing these auto-generated files, it might be better to consider
adding `mesos-endpoint-docs` to the website generating Rakefile.
> 
> Greg Mann wrote:
>     Perhaps it's good to have a static copy of the files committed to the repo, so that
a user who clones it has access to the docs without building and running the executable first?
> 
> Kevin Klues wrote:
>     @joseph, that was my initial thought as well. I talked about this with Greg, Ben,
and Neil though, and they thought was it was better to commit the .md files back to the repo.
 The idea being that eventually the .md files will be the source of truth that developers
modify and then we generate the help strings for c++ from that.  This will not be done immediately,
but that seems to be the plan (though I'm not sure I 100% agree with it).

In that case, I'd recommend adding a build step to run the auto-generator in `make`.  i.e.
If a help string changes, it'll show up in the `git diff`.

For example, the generated code for `protobuf_tests.proto` is also part of the code base.
 And we ensure this doesn't go out of sync via `make check`.


- Joseph


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


On Jan. 25, 2016, 11:42 p.m., Kevin Klues wrote:
> 
> -----------------------------------------------------------
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/42790/
> -----------------------------------------------------------
> 
> (Updated Jan. 25, 2016, 11:42 p.m.)
> 
> 
> Review request for mesos, Ben Mahler, Greg Mann, and Neil Conway.
> 
> 
> Repository: mesos
> 
> 
> Description
> -------
> 
> These .md files were auto generated using mesos-endpoints-help.
> 
> 
> Diffs
> -----
> 
>   docs/endpoints/files/browse.json/index.md PRE-CREATION 
>   docs/endpoints/files/browse.md PRE-CREATION 
>   docs/endpoints/files/debug.json/index.md PRE-CREATION 
>   docs/endpoints/files/debug.md PRE-CREATION 
>   docs/endpoints/files/download.json/index.md PRE-CREATION 
>   docs/endpoints/files/download.md PRE-CREATION 
>   docs/endpoints/files/read.json/index.md PRE-CREATION 
>   docs/endpoints/files/read.md PRE-CREATION 
>   docs/endpoints/index.md PRE-CREATION 
>   docs/endpoints/logging/toggle.md PRE-CREATION 
>   docs/endpoints/master/api/v1/scheduler.md PRE-CREATION 
>   docs/endpoints/master/create-volumes.md PRE-CREATION 
>   docs/endpoints/master/destroy-volumes.md PRE-CREATION 
>   docs/endpoints/master/flags.md PRE-CREATION 
>   docs/endpoints/master/frameworks.md PRE-CREATION 
>   docs/endpoints/master/health.md PRE-CREATION 
>   docs/endpoints/master/machine/down.md PRE-CREATION 
>   docs/endpoints/master/machine/up.md PRE-CREATION 
>   docs/endpoints/master/maintenance/schedule.md PRE-CREATION 
>   docs/endpoints/master/maintenance/status.md PRE-CREATION 
>   docs/endpoints/master/observe.md PRE-CREATION 
>   docs/endpoints/master/quota.md PRE-CREATION 
>   docs/endpoints/master/redirect.md PRE-CREATION 
>   docs/endpoints/master/reserve.md PRE-CREATION 
>   docs/endpoints/master/roles.json/index.md PRE-CREATION 
>   docs/endpoints/master/roles.md PRE-CREATION 
>   docs/endpoints/master/slaves.md PRE-CREATION 
>   docs/endpoints/master/state-summary.md PRE-CREATION 
>   docs/endpoints/master/state.json/index.md PRE-CREATION 
>   docs/endpoints/master/state.md PRE-CREATION 
>   docs/endpoints/master/tasks.json/index.md PRE-CREATION 
>   docs/endpoints/master/tasks.md PRE-CREATION 
>   docs/endpoints/master/teardown.md PRE-CREATION 
>   docs/endpoints/master/unreserve.md PRE-CREATION 
>   docs/endpoints/metrics/snapshot.md PRE-CREATION 
>   docs/endpoints/monitor/statistics.json/index.md PRE-CREATION 
>   docs/endpoints/monitor/statistics.md PRE-CREATION 
>   docs/endpoints/profiler/start.md PRE-CREATION 
>   docs/endpoints/profiler/stop.md PRE-CREATION 
>   docs/endpoints/registrar/registry.md PRE-CREATION 
>   docs/endpoints/slave/api/v1/executor.md PRE-CREATION 
>   docs/endpoints/slave/flags.md PRE-CREATION 
>   docs/endpoints/slave/health.md PRE-CREATION 
>   docs/endpoints/slave/state.json/index.md PRE-CREATION 
>   docs/endpoints/slave/state.md PRE-CREATION 
>   docs/endpoints/system/stats.json/index.md PRE-CREATION 
>   docs/endpoints/version.md PRE-CREATION 
>   site/Rakefile 0ce4b7975f95ab6930f0b2674191930df9ab5b20 
> 
> Diff: https://reviews.apache.org/r/42790/diff/
> 
> 
> Testing
> -------
> 
> 
> Thanks,
> 
> Kevin Klues
> 
>


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message