The documentations sources are in Markdown. From there, the proposed solution would be to use Jekill to generate HTML, plus a set of other scripts to automate the documentation for Javadoc, doxygen, REST API, CLI tools, protobuf definition, etc.
> The Apache website infrastructure is hosted in SVN. Some time back I was reading that some project are using GIT based publishing. That would work by committing the "generated" static website into a "asf-site" branch in the project repository. I would prefer git to avoid dealing with multiple source control system, though it would not be a big problem in any case. https://blogs.apache.org/infra/entry/git_based_websites_available On Mon, Jun 12, 2017 at 4:30 PM Dave Fisher <[email protected]> wrote: > The Apache website infrastructure is hosted in SVN. There are certain > requirements for links. > > It would be good to discuss. For example is the content in Markdown, XML, > HTML or what? It is not a big deal to conform. I have some experience from > moving OpenOffice.org to Apache. > > Regards. > Dave > > > On Jun 12, 2017, at 4:21 PM, Matteo Merli <[email protected]> wrote: > > > >> The project will need to have a minimal website. > > > > A colleague of mine, a technical writer, is going through the existing > > documentation, editing, expanding it and re-organizing it a bit. He's > also > > setting up the script and tools to generate a static website with links > to > > each version documentation. > > > > A pull-request will be ready in the next few days. We were also waiting > for > > the repo to be moved over to the ASF before starting with the website > > (because some nomenclature will change, copyright noticies, etc..). > > > > > > On Mon, Jun 12, 2017 at 2:11 PM Dave Fisher <[email protected]> > wrote: > > > >> Hi - > >> > >> The project will need to have a minimal website. I would be willing to > be > >> the test case about documentation. If it is enough for me to understand > how > >> to do development and use along with understanding the architecture > then it > >> will be good. > >> > >> I would recommend that a Wiki be used for shared design. There are many > >> approaches and some choices for the Wiki. Apache offers Confluence and > >> MOIN. Then there is Github. I am familiar with Confluence, but don’t let > >> that influence the project’s choice unduly. > >> > >> Here to help. > >> > >> Regards, > >> Dave > >> > >>> On Jun 12, 2017, at 12:55 PM, Matteo Merli <[email protected]> > >> wrote: > >>> > >>>> Is there specific criteria for determining whether documents are > >>> necessary or not? > >>> > >>> That's a good question. I don't have a precise answer for it. As > Andrews > >>> stated, it should > >>> allow any contributor to understand the new feature/changes, enough to > be > >>> able to > >>> do a meaningful code review and also serve as design documentation for > >>> future > >>> contributors. > >>> > >>> So, if after the discussion, some details are changed, the wiki should > be > >>> updated to > >>> reflect the final state. > >>> > >>> If one thinks that additional context is not required, he should go > ahead > >>> with a PR. And > >>> later we can discuss whether a design doc for that change would be > >>> beneficial or not. > >>> > >>> For candidates, and to give an example, I was thinking to start with a > >>> "Pulsar native proxy" > >>> proposal that I'm working on. Also, I think other good candidates would > >> be > >>> the > >>> non-persistent topics from Rajan, or the delivery throttling. > >>> > >>> > >>> > >>> On Thu, Jun 8, 2017 at 10:21 PM Sahaya Andrews < > [email protected] > >>> > >>> wrote: > >>> > >>>> On Thu, Jun 8, 2017 at 7:08 PM, Nozomi Kurihara < > [email protected] > >>> > >>>> wrote: > >>>>> Hi Matteo, > >>>>> > >>>>> ➢ The document doesn't need to be a super-detailed specification, but > >>>> should > >>>>> ➢ explain all the design points, reasons for choosing a > determined > >>>> solution, > >>>>> ➢ rejected alternatives and allow for other contributors to > >>>> understand the > >>>>> ➢ feature/change and to contribute as well to it. > >>>>> ➢ > >>>>> I agree with creating such design documents in the Wiki. > >>>>> > >>>>> ➢ for large code changes (new features, improvements) > >>>>> ➢ > >>>>> Is there specific criteria for determining whether documents are > >>>> necessary or not? > >>>> > >>>> One way to approach is how quickly someone new can understand the > >>>> architecture or a feature, so they can contribute back. > >>>> > >>>> Coming up with a list of such modules/features is not difficult. > >>>> > >>>> Andrews. > >>>> > >>>>> > >>>>> Thanks, > >>>>> Nozomi Kurihara > >>>>> > >>>>> 2017/06/09 5:13 に、"Matteo Merli" <[email protected]> を書き込みました: > >>>>> > >>>>> So far the discussion for large code changes (new features, > >>>> improvements) > >>>>> in the project has happened in a very informal way. > >>>>> > >>>>> As a way to improve community involvement and also to have a better > >>>>> internal > >>>>> documentation I would like to propose to adopt the PIP model that > >>>> many > >>>>> projects > >>>>> follow. > >>>>> > >>>>> Here, PIP would stand for "Pulsar Improvement Proposal" and would > >>>> consist > >>>>> in creating design documents in the Wiki with a sequential id. > >>>>> > >>>>> The document doesn't need to be a super-detailed specification, but > >>>> should > >>>>> explain all the design points, reasons for choosing a determined > >>>> solution, > >>>>> rejected alternatives and allow for other contributors to > understand > >>>> the > >>>>> feature/change and to contribute as well to it. > >>>>> > >>>>> The advantage would be to have a preliminary discussion and gather > >>>> feedback > >>>>> on the design itself and also have the proposals there as a > >>>> reference. > >>>>> > >>>>> In some cases the design has been discussed over "issues" or PRs > but > >>>> then > >>>>> later it's more difficult to understand the whole picture, since > the > >>>>> information is fragmented. > >>>>> > >>>>> Opinions? > >>>>> > >>>>> Matteo > >>>>> > >>>>> > >>>>> > >>>>> > >>>> > >> > >> > >
