[range][documentation] - best practice for generating documentation?
Hi, I'm currently the suitably ashamed owner of numerous documentation trac issues for Boost.Range. I would like to address these issues but I'm unclear about what our strategy is for generating documentation since our move to modular Boost. I anticipate that if I continue to commit the generated html as I had done previously that I will be in for a "world of pain" when it comes to merge to master. I've searched and found several pages about document best-practice but the pages contain references to the subversion repository which leads me to believe that this must be out-of-date. I'd like some advice to ensure that my commits are aligned with what is wanted. If there is a temporary workflow I can use that will not end in a merge disaster then I'd like to put small documentation fixes in quickly before major re-factoring of the documentation generation process. I apologise in advance if my search skills have been deficient. Sending a link accompanied with abuse is entirely acceptable! Thanks, Neil Groves
On 3 March 2014 16:15, Neil Groves <neil@grovescomputing.com> wrote:
Hi,
I'm currently the suitably ashamed owner of numerous documentation trac issues for Boost.Range. I would like to address these issues but I'm unclear about what our strategy is for generating documentation since our move to modular Boost. I anticipate that if I continue to commit the generated html as I had done previously that I will be in for a "world of pain" when it comes to merge to master.
You probably won't if you keep the merges simple, although cherry picking and bi-directional merges would cause problems. But if you want, I can add it to the documentation build and you can remove the generated html from your repo.
I've searched and found several pages about document best-practice but the pages contain references to the subversion repository which leads me to believe that this must be out-of-date.
I don't think there is a page. There are some pages on the Wiki which are probably all out of date. If there's anything on the main site that needs updating, let me know.
On Mon, Mar 3, 2014 at 4:28 PM, Daniel James <dnljms@gmail.com> wrote:
On 3 March 2014 16:15, Neil Groves <neil@grovescomputing.com> wrote:
Hi,
You probably won't if you keep the merges simple, although cherry picking and bi-directional merges would cause problems. But if you want, I can add it to the documentation build and you can remove the generated html from your repo.
Yes please do put it into the build and then I shall discard the html. I assume this is the new best-practice. I think this will be much better. Please let me know if there is anything I need to do to make this process work? I have some time at the moment to really knuckle down and sort this out.
I've searched and found several pages about document best-practice but the pages contain references to the subversion repository which leads me to believe that this must be out-of-date.
I don't think there is a page. There are some pages on the Wiki which are probably all out of date. If there's anything on the main site that needs updating, let me know.
I didn't see anything on the main site that was out-of-date. It seems to me that the documentation being part of the build is an exciting improvement that most maintainers would want to adopt. It might be worthwhile just to put up a small page about this process. It might save time answering daft questions from people like me. Thanks for helping. Regards, Neil Groves
On 3 March 2014 17:28, Neil Groves <neil@grovescomputing.com> wrote:
Yes please do put it into the build and then I shall discard the html. I assume this is the new best-practice. I think this will be much better. Please let me know if there is anything I need to do to make this process work? I have some time at the moment to really knuckle down and sort this out.
It's included in the build now, it was just a case of adding it to the list of libraries in the build scripts. You can see the documentation at: http://boost-sandbox.sourceforge.net/libs/range/
participants (2)
-
Daniel James -
Neil Groves