Le samedi 30 janvier 2021, 19:41:55 CET Oleg Kalnichevski a écrit : > On Sat, 2021-01-30 at 18:16 +0100, Hervé BOUTEMY wrote: > > Hi, > > > > As promised, here is an explanation of where we are and where we go > > next. > > Hi Hervé > > I think I now more or less understand the overall process. Thank you > for your help and explanations. glad that you now see the overall scheme. I will remain with you all to finish details
> > If you still have some spare time and good will left to help us, please > help us simplify the main project website by, for instance, switching > it from APT to Markdown (or some other alternative discussed in the > past). I don't know yet magical solution for going from Apt to Markdown, but I suppose this is something many people are interested in: I'll see how we could create reusable helpers One useful thing that we can do is adding "edit" icon like we have on the Maven website, the little icon in breadcrumb: https://maven.apache.org/ This would ease finding the source file from a page, then edit easily in Github (eventually forking to create a PR). From Maven experience, it eases things a lot both for contributors (who don't know details), but even for seasoned developers, who know, but find it cumbersome to find the source. WDYT? > > Oleg > > > HttpCore and HttpClient have been updated to publish their > > documentation generated from source to: > > http://hc.apache.org/components/httpcomponents-core-5.1.x/LATEST and > > http://hc.apache.org/components/httpcomponents-client-5.0.x/LATEST > > > > At any time, during SNAPSHOT development or at release staging time, > > documentation can be: > > 1. generated from source code: mvn site site:stage > > 2. then published to LATEST directory: mvn scm-publish:publish-scm > > by any team member (once initial directory creation in svn will be ok > > [1]) > > > > > > Integration of this documentation to the main site requires to merge > > next PR: > > https://github.com/apache/httpcomponents-website/pull/9 > > It will create symbolic links that will inject content in normal > > website directories (without the "/components/" parts that seems > > strange, explanation will follow...) > > > > When you'll do a release, the release manager will publish the > > documentation and provide "LATEST" url, for review during the vote. > > Once the vote will be ok, the state of the staging documentation will > > have to be marked as a release: this will be done with a "svn cp" > > command, like shown in the website PR [2] > > > > > > Why this components/ directory? > > The html website consists of the main website "unversioned" content > > and the documentation generated from source (LATEST and every release > > that the project will want to keep online). > > If you build unversioned website and look at "target/site", you'll > > see that the content is 1,112 kB for 75 files. > > But if you look at the content in svn [3], there are currently 51,740 > > files for 1,071,288 kB: there is documentation for each component > > branch, and that documentation will grow in the future with LATEST > > and every release > > Then the website publication job on Jankins [4] will in the future > > svn checkout more and more content to update only these 75 files that > > are the unversioned content. > > > > Separating documentation in a separate directory of the site is a > > first step to fix this scalability issue: in a second step, we'll > > move this svn directory to a location that is fully separate, then > > won't be checked out by website publication job. > > > > > > I hope this explanation helps everybody understand how release > > documentation will be published easily and kept as much as you need. > > > > Regards, > > > > Hervé > > > > > > [1] https://github.com/apache/httpcomponents-client/pull/280 > > > > [2] > > https://github.com/apache/httpcomponents-website/pull/9/files#diff-750296d > > b9b9b33a71f10fa5eda497d2aabe583aad8be1b87a5ea2bb89957bcdf > > > > [3] https://svn.apache.org/repos/asf/httpcomponents/site/ > > https://svn.apache.org/viewvc/httpcomponents/site/ > > > > [4] > > https://ci-builds.apache.org/job/HttpComponents/job/HttpComponents%20Websi > > te/ > > > > > > > > --------------------------------------------------------------------- > > To unsubscribe, e-mail: [email protected] > > For additional commands, e-mail: [email protected] > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
