search

cloudstateio / cloudstate

Distributed State Management for Serverless
https://cloudstate.io
Apache License 2.0
763 stars 97 forks source link

Antora mn #409

Closed rstento closed 3 years ago

rstento commented 3 years ago

@michaelpnash, I fixed the sample includes where possible and the xreferences to javadoc and javascript. The xreferences are using variables so they can be fixed once the javadoc and javascript are generated in their new locations. @pvlugter, it would be great to merge this so that we can start working on CI integration. It won't impact the existing docs until we have automated the build and are ready to switch over to publishing the Antora docs.

pvlugter commented 3 years ago

It's a bit hard to follow with the merges from master included as well, could be better to just base on the antora branch; and also with @michaelpnash pushing directly to the antora branch without pull requests.

Looks like the samples have been copied manually into the antora directories now. Does this mean they're no longer compiled and tested by the build? If they're an extra copy, then they'll also easily get out-of-date. We really don't want to move in this direction, but instead have as many of the code samples verified as part of the build. I expect there's some plan for this, but it's unclear currently with the given changes.

The javadoc and jsdoc seem to have lost linking directly to methods, and just point at classes/pages now. That's a shame. Can we improve this? And the javadoc and jsdoc links use a https://cloudstate.io/docs/... reference now — so looks like the docs with API links can't be previewed locally?

rstento commented 3 years ago

I believe @michaelpnash discussed the samples with James and they decided this was the simplest solution. The samples can still be validated as part of the build, the samples directory would just need to be added, right?

Ruth Stento User Experience Lead Lightbend

512-696-1448 http://lightbend.com

On Sun, Aug 16, 2020 at 9:25 PM Peter Vlugter notifications@github.com wrote:

It's a bit hard to follow with the merges from master included as well, could be better to just base on the antora branch; and also with @michaelpnash https://github.com/michaelpnash pushing directly to the antora branch without pull requests.

Looks like the samples have been copied manually into the antora directories now. Does this mean they're no longer compiled and tested by the build? If they're an extra copy, then they'll also easily get out-of-date. We really don't want to move in this direction, but instead have as many of the code samples verified as part of the build. I expect there's some plan for this, but it's unclear currently with the given changes.

The javadoc and jsdoc seem to have lost linking directly to methods, and just point at classes/pages now. That's a shame. Can we improve this? And the javadoc and jsdoc links use a https://cloudstate.io/docs/... reference now — so looks the docs with API links can't be previewed locally?

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/cloudstateio/cloudstate/pull/409#issuecomment-674622709, or unsubscribe https://github.com/notifications/unsubscribe-auth/AFOUG64BOUROYJ6MP7XL5FDSBCIIVANCNFSM4QAKNK5Q .

michaelpnash commented 3 years ago

@pvlugter Yes, moving or linking the samples to the expected dir structure for the doc seems to be less painful than the custom plugin, at least that's the premise in this PR - of course we don't want to have dups, so either a link or actually moving directories seems better, but I'm not sure which is preferable - so I did neither, just for the purposes of an example.

WDYT?

pvlugter commented 3 years ago

Sure, moving the sample code under antora directories, and possibly link or otherwise using that location directly, all sounds fine. Also discussed in #384.

It would be good for transparency to have discussions added to github, and changes in pull requests rather than pushed directly, so it's easier to follow.

pvlugter commented 3 years ago

Looking at this more closely, and the changes pushed directly to the antora branch. The samples has been copied over, but the current documentation examples come from docs/src/test. I'll reset the antora branch and move+link the right files.

pvlugter commented 3 years ago

Moved the doc examples under antora modules in #415. This PR will need to be rebased and updated, now that the correct files should be there for examples. I'll look at which changes should be kept and make updates here directly.

pvlugter commented 3 years ago

Since the examples are different from in this PR, and there were other paradox/markdown to asciidoc conversions to do, I've created a new PR with the code snippet and other conversions in #416. I haven't done anything with the javadoc or jsdoc extrefs yet — and would prefer a way to have available locally as well (not refs to cloudstate.io site, which will only be updated on publish).

pvlugter commented 3 years ago

Added the API docs to the site and converted the @javadoc and @extref jsdoc links in #418.

I'll close this PR now.