I think this is just for the rest api reference; I would still expect us to
provide some api examples in the user guide.
I expect we could get swagger to build into the api reference docs into the
user/target directory and then cross link from the sphinx user guide
(although I note that they have a generator for "confluence wiki" ).
--
Jody Garnett
On 6 February 2017 at 12:50, Mike Pumphrey <[email protected]> wrote:
> Hi Matt.
>
> I am all about improvements to documentation, and using the right tool
> for the job, and not being stuck with past decisions.
>
> However, I second a few of Andrea's concerns. Unless we're going to
> migrate all of our docs to Swagger, how would it work to have
> documentation build using two different build tools? Do we trust Swagger
> to be around for a while?
>
> That said, API docs and regular docs are kind of different things. I
> believe it could be possible to have both, a more human-written
> documentation of the REST API (in our Sphinx docs) and separately a
> from-the-code generated API docs, kind of like Javadocs I imagine.
>
> Thanks,
> Mike
>
> Mike Pumphrey
> Education Program Director | Boundless
> 917-338-0407
> [email protected]
> http://boundlessgeo.com
> @boundlessgeo
>
> On 2/3/2017 10:05 AM, Andrea Aime wrote:
> > HI Matt,
> > I don't know the tool, but wondering:
> >
> > - Is it going to make the REST api documentation into a separate
> > documentation set as the user docs?
> > - Can we version it along with GeoServer like we do with the user
> docs?
> > - Can it be customized to have the GeoServer colors and logos?
> > - What about restlets that require longer docs, are these going to be
> > embedded in the code?
> >
> > It's also the first time I see the wiki page. The "Annotation driven"
> part
> > scares me quite a bit, can you make
> > sure the annotation classpath scan is not going to make the startup time
> > longer? We are constantly fighting to keep
> > it at bay, we might have to make sure the packages containing
> >
> > Cheers
> > Andrea
> >
> >
> > On Fri, Feb 3, 2017 at 5:55 PM, Matt Kruszewski <
> > [email protected]> wrote:
> >
> >> Hi Mike,
> >>
> >> Given the upcoming switch to Spring MVC for the REST API, I wanted to
> >> start a conversation about possible improvements for the REST
> documentation
> >> (GEOS-7931). One option is Swagger, which has a lot of supporting
> tooling
> >> and is able to automatically generate docs from Spring MVC annotations
> --
> >> though some additional annotations might be required to flesh things
> out.
> >> What experience does everyone have with REST documentation formats and
> >> tools?
> >>
> >> Jody and I are doing some initial research and prototyping, and we have
> >> gathered our notes so far on the wiki (https://github.com/geoserver/
> >> geoserver/wiki/REST-API-Refresh).
> >>
> >> Thanks,
> >> Matt Kruszewski
> >>
> >> ------------------------------------------------------------
> >> ------------------
> >> Check out the vibrant tech community on one of the world's most
> >> engaging tech sites, SlashDot.org! http://sdm.link/slashdot
> >> _______________________________________________
> >> Geoserver-devel mailing list
> >> [email protected]
> >> https://lists.sourceforge.net/lists/listinfo/geoserver-devel
> >>
> >>
> >
> >
>
> ------------------------------------------------------------
> ------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, SlashDot.org! http://sdm.link/slashdot
> _______________________________________________
> Geoserver-devel mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/geoserver-devel
>
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, SlashDot.org! http://sdm.link/slashdot
_______________________________________________
Geoserver-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/geoserver-devel
