You are viewing a plain text version of this content. The canonical link for it is here.
Posted to server-dev@james.apache.org by Tellier Benoit <bt...@apache.org> on 2020/07/05 15:44:45 UTC
Building Antora documentation
Hi all,
In an evening effort, I started writing a documentation skeleton for the
Distributed James server with the new Antora Documentation.
In order to juge the results I came up with (and do some corrections as
I am new to this technology) I would like to generate the result of my work.
I don't think I saw explanations of how to generate the James
documentation website, I tried running some commands on the Antora
website but I did not achieve anything conclusive.
Can someone provide me the commands needed to generate the documentation
website? (I successfully installed Antora and http-server)
Regards,
Benoit
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org
Re: Building Antora documentation
Posted by Tellier Benoit <bt...@apache.org>.
Le 10/07/2020 à 07:34, David Leangen a écrit :
> Hi Eugen,
>
> Thank you very much for all your efforts. The community is fortunate that you are able to dedicate so much concentrated effort.
>
>> I've given up on building the old site since I failed several times.
> I think that’s ok, though. Honestly, I don’t see a viable path forward in terms of “migrating” the old docs. Yes, there is some good information still in those docs, and some good stuff that could inspire the new docs, however, I think the only practical way forward is to start over, from a top-down perspective. IMO, we need to make a clean break, and at the same time re-evaluate the James mission. (But that’s just my opinion and I’m just a newbie so my voice doesn’t hold as much weight.)
In my opinion the current doc lacks structure.
We miss some concept and "architecture" forwords. We miss a "per server
documentation".
What I mean is that we don't need to write all over again, but in the
process of migrating things we can identify what is missing.
>
> I like the inventory. I can use that as a checklist to make sure the new docs aren’t leaving anything out. Or maybe the old docs could be assembled for the “developer” part of the site, aimed at experienced James developers who already know their way around and just need a reference. But I don’t see how the current docs could be useful for Operators or Integrators who don’t have experience with James.
I prefer dropping it altogether.
We need to simplify things. And the mvn site don't handle versionning.
Even for experienced people I doubt that it can bring value compared to
Antora.
>
> So with that in mind...
>
>> I've create two issues to track the progress of migrating the old site
>> to Antora.
>>
>> * Make an inventory of old site
>> https://issues.apache.org/jira/browse/JAMES-3301
> Cool, thanks! I think this can be useful.
I will have a look, but I don't know if it will be today ;-)
>> * Migrate the content https://issues.apache.org/jira/browse/JAMES-3302
>>
>> Please help out with the inventory and if you have ideas with the content.
>>
>> I'll migrate what I can, we can sort them after.
> I don’t think that’s necessary, but if it’s already done, then great.
IMO:
- Having the ADRs part of the website is nice
- For the over contents part of the "migrated" module, we should think
of it as an help for the actual doc writing.
>
>
> Thanks again!
> =David
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org
Re: Building Antora documentation
Posted by David Leangen <ap...@leangen.net>.
Hi Eugen,
Thank you very much for all your efforts. The community is fortunate that you are able to dedicate so much concentrated effort.
> I've given up on building the old site since I failed several times.
I think that’s ok, though. Honestly, I don’t see a viable path forward in terms of “migrating” the old docs. Yes, there is some good information still in those docs, and some good stuff that could inspire the new docs, however, I think the only practical way forward is to start over, from a top-down perspective. IMO, we need to make a clean break, and at the same time re-evaluate the James mission. (But that’s just my opinion and I’m just a newbie so my voice doesn’t hold as much weight.)
I like the inventory. I can use that as a checklist to make sure the new docs aren’t leaving anything out. Or maybe the old docs could be assembled for the “developer” part of the site, aimed at experienced James developers who already know their way around and just need a reference. But I don’t see how the current docs could be useful for Operators or Integrators who don’t have experience with James.
So with that in mind...
> I've create two issues to track the progress of migrating the old site
> to Antora.
>
> * Make an inventory of old site
> https://issues.apache.org/jira/browse/JAMES-3301
Cool, thanks! I think this can be useful.
> * Migrate the content https://issues.apache.org/jira/browse/JAMES-3302
>
> Please help out with the inventory and if you have ideas with the content.
>
> I'll migrate what I can, we can sort them after.
I don’t think that’s necessary, but if it’s already done, then great.
Thanks again!
=David
Re: Building Antora documentation
Posted by Eugen Stan <eu...@netdava.com>.
I've given up on building the old site since I failed several times.
I've create two issues to track the progress of migrating the old site
to Antora.
* Make an inventory of old site
https://issues.apache.org/jira/browse/JAMES-3301
* Migrate the content https://issues.apache.org/jira/browse/JAMES-3302
Please help out with the inventory and if you have ideas with the content.
I'll migrate what I can, we can sort them after.
I've migrated the markdown files for ADR and src/site/markdown using
kramdown .
I have found a migration from XDOC/APT -> DocBook -> AsciiDoc , but did
not try it yet.
See my code here: https://github.com/apache/james-project/pull/234 .
Feedback is welcomed.
We might not get gradle soon since migration is stalling but I think we
can get the website.
IMO it is a smaller enterprise and with a bit more immediate impact.
Regards,
La 09.07.2020 20:09, Eugen Stan a scris:
> Hello Benoit,
>
> I've added the list since you missed to include it.
>
> Thanks for the reply. I missed this information and asked again in my
> second email.
>
> I think we can work in this thread and ignore the other.
>
> See my reply inline:
>
> La 08.07.2020 09:33, Tellier Benoit a scris:
>> Le 06/07/2020 à 14:17, Eugen Stan a écrit :
>>> Hello David,
>>>
>>> Thanks for the guide.
>>>
>>> I think we can work on a branch on top of
>>> https://github.com/apache/james-site/tree/asf-site
>>>
>>>
>>> @Benoit: Regarding https://issues.apache.org/jira/browse/JAMES-3226 .
>>>
>>> What is the current process of deploying the james-site ?
>>>
>> Instructions can be found here:
>>
>> https://github.com/apache/james-project#how-to-build-and-publish-the-website
>>
>>
>> - Build the homepage (using jekyll) ( james-project/src/homepage )
>>
>> Commands could be extracted from the dockerfile:
>>
>> https://github.com/apache/james-project/tree/master/dockerfiles/site/homepage
> Using docker to build the hompage is ok I guess.
>
> I would push a pre-built image instead of always building it.
>
> I do think we should move the all the site information to james-site
> project.
>
> We can have the code there and use orphan branches for publishing the
> website.
>
> We can drop and remake those branches to keep the repo slim.
>
> It's good to know that the site is generated and we can drop asf-site
> when we need to.
>
>
> Moving to Antora I guess we should decide if we want to maintain a
> separate homepage using Jekill or port things to Antora.
>
> I like simple things and dropping an extra tool makes sense.
>
> We do have to figure out what will be the porting effort.
>
> I wonder what everyone else thinks about this. (Hint for everyone to
> speak their mind).
>
> I've managed to build the homepage.
>
>> - Build the (mvn) documentation site (james-project/src/site )
>>
>> Which is slow...
>>
>> Commands could be extracted from the dockerfile:
>>
>> https://github.com/apache/james-project/tree/master/dockerfiles/site/website
>>
>> I do run them without docker.
> I failed to build the site using docker. Any ideas (did not have time to
> investigate yet) ?
>
> ----
>
> [ERROR] [ERROR] Could not find the selected project in the reactor:
> mpt/antlib @
> [ERROR] Could not find the selected project in the reactor: mpt/antlib
> -> [Help 1]
>
> ----
>
>> Then specify the output (or copy it) to james-site project, commit &
>> push. (I said it was dirty)
>>
>> Note that there is often (always) a synchronisation issue: changes are
>> not applied. I raised the point with the infra (can't recall the ticket)
>> and their proposal solution is to do a dummy one line commit (pushed
>> separately) after the site modification, which immediatly makes the
>> changes visible.
>>
>> This answers your question?
> Yes, it answers my questions. Thank you.
>
> My proposal so far is to:
>
> 1. Figure out if we can leverage Antora for the homepage as well (I
> believe we can, but I need to check).
>
> This will simplify our build setup.
>
> 2. Prepare a new website on james-site and migrate the existing content
> there.
>
> I hope we get to do a community push on this. It's not sexy but I think
> we can convert the existing pages to Asciidoc.
>
> Migrating the content is important - not all of it is relevant but a lot
> is IMO.
>
>>> I'll work on a branch and try to automate that or parts of that.
>> +1 <3 today it is painful.
>>> My goal is to also incorporate antora into the mix.
>> +1 I would love to have it as a subfolder of current website until we
>> can fully switch to it.
> I agree.
>
>
>>> I've created this to track work on it
>>> https://github.com/apache/james-site/pull/1 .
>>>
>>> We can discuss there for specific technical aspects.
>> I had a read, it sounds good to me.
>>
>> Regards,
>>
>> Benoit
>>
--
Eugen Stan
+40720 898 747 / netdava.com
Re: Building Antora documentation
Posted by Eugen Stan <eu...@netdava.com>.
Hello Benoit,
I've added the list since you missed to include it.
Thanks for the reply. I missed this information and asked again in my
second email.
I think we can work in this thread and ignore the other.
See my reply inline:
La 08.07.2020 09:33, Tellier Benoit a scris:
> Le 06/07/2020 à 14:17, Eugen Stan a écrit :
>> Hello David,
>>
>> Thanks for the guide.
>>
>> I think we can work on a branch on top of
>> https://github.com/apache/james-site/tree/asf-site
>>
>>
>> @Benoit: Regarding https://issues.apache.org/jira/browse/JAMES-3226 .
>>
>> What is the current process of deploying the james-site ?
>>
> Instructions can be found here:
>
> https://github.com/apache/james-project#how-to-build-and-publish-the-website
>
>
> - Build the homepage (using jekyll) ( james-project/src/homepage )
>
> Commands could be extracted from the dockerfile:
>
> https://github.com/apache/james-project/tree/master/dockerfiles/site/homepage
Using docker to build the hompage is ok I guess.
I would push a pre-built image instead of always building it.
I do think we should move the all the site information to james-site
project.
We can have the code there and use orphan branches for publishing the
website.
We can drop and remake those branches to keep the repo slim.
It's good to know that the site is generated and we can drop asf-site
when we need to.
Moving to Antora I guess we should decide if we want to maintain a
separate homepage using Jekill or port things to Antora.
I like simple things and dropping an extra tool makes sense.
We do have to figure out what will be the porting effort.
I wonder what everyone else thinks about this. (Hint for everyone to
speak their mind).
I've managed to build the homepage.
> - Build the (mvn) documentation site (james-project/src/site )
>
> Which is slow...
>
> Commands could be extracted from the dockerfile:
>
> https://github.com/apache/james-project/tree/master/dockerfiles/site/website
>
> I do run them without docker.
I failed to build the site using docker. Any ideas (did not have time to
investigate yet) ?
----
[ERROR] [ERROR] Could not find the selected project in the reactor:
mpt/antlib @
[ERROR] Could not find the selected project in the reactor: mpt/antlib
-> [Help 1]
----
> Then specify the output (or copy it) to james-site project, commit &
> push. (I said it was dirty)
>
> Note that there is often (always) a synchronisation issue: changes are
> not applied. I raised the point with the infra (can't recall the ticket)
> and their proposal solution is to do a dummy one line commit (pushed
> separately) after the site modification, which immediatly makes the
> changes visible.
>
> This answers your question?
Yes, it answers my questions. Thank you.
My proposal so far is to:
1. Figure out if we can leverage Antora for the homepage as well (I
believe we can, but I need to check).
This will simplify our build setup.
2. Prepare a new website on james-site and migrate the existing content
there.
I hope we get to do a community push on this. It's not sexy but I think
we can convert the existing pages to Asciidoc.
Migrating the content is important - not all of it is relevant but a lot
is IMO.
>> I'll work on a branch and try to automate that or parts of that.
> +1 <3 today it is painful.
>> My goal is to also incorporate antora into the mix.
> +1 I would love to have it as a subfolder of current website until we
> can fully switch to it.
I agree.
>> I've created this to track work on it
>> https://github.com/apache/james-site/pull/1 .
>>
>> We can discuss there for specific technical aspects.
> I had a read, it sounds good to me.
>
> Regards,
>
> Benoit
>
--
Eugen Stan
+40720 898 747 / netdava.com
Re: Building Antora documentation
Posted by Eugen Stan <eu...@netdava.com>.
Hello David,
Thanks for the guide.
I think we can work on a branch on top of
https://github.com/apache/james-site/tree/asf-site
@Benoit: Regarding https://issues.apache.org/jira/browse/JAMES-3226 .
What is the current process of deploying the james-site ?
I'll work on a branch and try to automate that or parts of that.
My goal is to also incorporate antora into the mix.
I've created this to track work on it
https://github.com/apache/james-site/pull/1 .
We can discuss there for specific technical aspects.
Regards,
--
Eugen Stan
+40720 898 747 / netdava.com
Re: Building Antora documentation
Posted by David Leangen <ap...@leangen.net>.
Hi Benoit,
> In an evening effort, I started writing a documentation skeleton for the
> Distributed James server with the new Antora Documentation.
Awesome, thanks!
> In order to juge the results I came up with (and do some corrections as
> I am new to this technology) I would like to generate the result of my work.
I just created an issue for this:
https://issues.apache.org/jira/browse/JAMES-3258
> Can someone provide me the commands needed to generate the documentation
> website? (I successfully installed Antora and http-server)
In the meantime, here I will explain how you can generate it locally. Since you have already installed Antora, this should be all you need to do:
Create a local file with contents like this (replacing with a hard-coded value your correct local [path-to-local-repos]):
[local-antora-playbook.yml]
```
site:
title: Apache James
url: https://james.apache.org/
start_page: main::index.adoc
content:
sources:
- url: [path-to-local-repos]/james-project
branches: HEAD
start_path: docs
- url: [path-to-local-repos]/james-jsieve
branches: HEAD
start_path: docs
ui:
bundle:
url: [path-to-ui-bundle]/ui-bundle.zip
runtime:
fetch: true
```
To visualize the results correctly, I will need to send you the ui-bundle.zip. I will attach it to the issue.
(We need to create our own ui-bundle.zip, which creates the page outline, includes the James branding etc.)
To run the build, just do:
```
antora local-antora-playbook.yml
```
Then open your browser and go to file:///[path-to-your-playbook]/build/site/main/3.5/index.html
Let me know if you have any issues and I will try to help you out. I am by no means an expert in Antora, but I do have it working just fine locally.
Cheers,
=David