[GitHub] sterlinghughes commented on issue #706: Continued conversion of mynewt-site docs to core with doxygen integration.

[GitBox <gi...@apache.org>]

sterlinghughes commented on issue #706: Continued conversion of mynewt-site docs to core with doxygen integration.
URL: https://github.com/apache/mynewt-core/pull/706#issuecomment-352819637
 
 
   HI @jacobrosenthal --- I definitely think we should clone at depth 1 as your previous PR points out.  We do need to manage upgrade & sync, and make sure we are properly handling the source control.  We avoided depth 1 just to be cautious around that, but with the repo size exploding we probably do need to manage that.
   
   Personally, I think having the documentation inline with the source code makes a lot of sense, because the documentation then tracks the released version of source code, and can be generated.  This makes thing easier to maintain, especially as we break out individual projects.  There have been efforts to break out significant components: 
   
   - https://github.com/runtimeco/mcuboot
   - https://github.com/apache/mynewt-nimble
   - https://github.com/apache/mynewt-mcumgr
   - https://github.com/apache/mynewt-nffs
   
   With the hope of making these independently released and documentable as well.  The idea has been to let those stabilize and work as independent projects before removing them from *-core (as well as improving newt so that i can truly work easily/well with multiple repos.) In my mind, this constitutes Mynewt 2.0.  
   
   In order to move to separately releasable components, it would be nice if the documentation was contained within the source repo (and tracked the release trains.)  But we also need to make sure we evolve the documentation (& add a lot more doxygen for function descriptions) so that we can actually have this mostly working as well.  Thus the thought to begin moving the documentation into the source tree, and get it generating reliably/have it become the source of truth.
   
   I think this may be a topic for dev@ if somebody can move it over.
   
   
   

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services