Migrate docs from Akka/Akka here, using Paradox #1
Comments
|
Docs will then be published to |
|
Then we would probably want to implement the automatic rst->paradox converter first. It's then needed sooner than I first thought of. Note that @drewhk is interested in writing the converter tool. |
|
We could move sphinx, but since that will need re-working paths of includes anyway I thought it might be better to take the hit all at once. Open to suggestions ofc |
|
yeah, it all depends on how big the effort is. Let's spend at most 2 days on the converter tool and then community can hopefully do the actual conversion and manual adjustments. |
|
Yeah, there was some intent to help signalled on gitter, I hope we'll be able to move it over without too much pain |
|
I can do a timeboxed try with Laika to estimate the effort. I used it before on akka-docs (for different purpose) and it is not rocket science. |
|
It can be "mostly" correct, we'll fix the rest manually |
ktoso
added
the
1 - triaged
|
As far as I got playing around with Laika: https://github.com/johanandren/akkadocs-sphinx2paradox |
|
Heh, maybe I should add exactly how far that was: Some special stuff still not covered, includecode works but not includecode2 yet, warning/info boxes becomes regular text with bold header. Got some warning from some markup, can't remember exactly what it was. |
|
@johanandren I added a few additional code on top of your repo here: https://github.com/jonas/akkadocs-sphinx2paradox The current state (with A list of things to resolve:
Dependencies: |
ktoso
added
t:docs
|
This is great, I'll move existing docs into this repo today and get the build to work as well. |
|
WIP branch: https://github.com/jonas/akka-http/tree/wip-paradox |
|
Does that mean it does not make sense for us to import historic commits? #289 |
|
@jonas we've rewritten the whole history one last time again to include history for documentation as well but it's now missing a few infrastructure and auxiliary files. Depending on what's your base for the rewriting you/we may have to copy over other files over from akka again. It's also fine if you continue working on your current version (trying to rebase to our new state might conflict) and we polish just the final result coming out from your conversion. WDYT? |
|
@jrudolph I've rebased on top of the updated rewritten history you pushed. The next question is how close to working the conversion needs to be before such a PR is acceptable. The main blocker right now is extracting link text for the ~500 cross-reference (likely doable with some sed scripts to feed the conversion tool) and making the directive snippets work. The latter will be a lot of work and I am wondering if it would be better to leave it broken for now and instead try to solve it via #11 or some interim preprocessing tool that extracts directive docs or snippets from code comments. |
|
I think an initial PR would be good already. For the "needs lots of work" perhaps we'd get some help from the community |
Converts .rst files to .md using: - https://github.com/jonas/akkadocs-sphinx2paradox Fixes akka#1
Converts .rst files to .md using: - https://github.com/jonas/akkadocs-sphinx2paradox Fixes akka#1
Converts .rst files to .md in a best effor way using: - https://github.com/jonas/akkadocs-sphinx2paradox Fixes akka#1
Converts .rst files to .md in a best effor way using: - https://github.com/jonas/akkadocs-sphinx2paradox References akka#1
Converts .rst files to .md in a best effor way using: - https://github.com/jonas/akkadocs-sphinx2paradox References akka#1
* Fix warnings being treated as a comment
* Fix space after # in markers
> find docs/ -name "*.scala" | xargs sed -i 's,//# ,//#,'
> find docs/ -name "*.java" | xargs sed -i 's,//# ,//#,'
* Fix missing explicit snippet end markers
> find docs/rst/ -type f | xargs grep -l '//#$' | sort -u
* Add index files
* Fix literalinclude paths
* Initial work on fixing missing or non-supported snippet markers
* Fix includecode paths
> find docs/rst/ -type f | while read file; do up=$(cd $(dirname $file) && git rev-parse --show-cdup); sed -i "s#\(includecode2\?:: \).*\(/akka-http\)#\1$up../..\2#" $file; done
> find docs/rst/ -type f | while read file; do up=$(cd $(dirname $file) && git rev-parse --show-cdup); sed -i "s#\(includecode2\?:: \)/../../#\1$up../../#" $file; done
* Move Java and Scala example code to src/test/{java,scala}
> git mv docs/rst/java/code docs/src/test/java
> find docs/rst/java/ -name "*.rst" | xargs sed -i 's#/code/#/../../../test/java/#'
> git mv docs/rst/scala/code docs/src/test/scala
> find docs/rst/scala/ -name "*.rst" | xargs sed -i 's#/code/#/../../../test/scala/#'
* Remove stylistic rst-class directives
* Replace multiple snippets per lines with shared snippet
* =doc Migrate docs from Sphinx to Paradox
Converts .rst files to .md in a best effor way using:
- https://github.com/jonas/akkadocs-sphinx2paradox
References #1
* =doc Improve conversion of routing DSL and client-side API overviews
* Fix the docs build
Broken by moving example code to docs/src/test in 926a3b8
* Fixup: Apply docFormatSettings and revert some debug build code
* Minor improvements to @@toc rendering and fix included config files having type=none
|
Not marking as resolved yet, until we've made it to an actual rendered page on doc.akka.io :) |
|
I saw the ticket about redirecting akka.github.io/akka-http to doc.akka.io/http. Do we also need a ticket for porting the theme? Let me know how I can help. |
|
Yes and no, I was hoping to get a designer help us do a proper new theme. |
|
AKA we don't want to spend a lot of time on porting the theme just jet |
|
Done thanks to the relentless efforts of @jonas! Thanks a lot! |
|
@ktoso 👍 I would like to keep contributing as time permits. For now I will mainly focus on tooling and documentation. |
* Fix warnings being treated as a comment
* Fix space after # in markers
> find docs/ -name "*.scala" | xargs sed -i 's,//# ,//#,'
> find docs/ -name "*.java" | xargs sed -i 's,//# ,//#,'
* Fix missing explicit snippet end markers
> find docs/rst/ -type f | xargs grep -l '//#$' | sort -u
* Add index files
* Fix literalinclude paths
* Initial work on fixing missing or non-supported snippet markers
* Fix includecode paths
> find docs/rst/ -type f | while read file; do up=$(cd $(dirname $file) && git rev-parse --show-cdup); sed -i "s#\(includecode2\?:: \).*\(/akka-http\)#\1$up../..\2#" $file; done
> find docs/rst/ -type f | while read file; do up=$(cd $(dirname $file) && git rev-parse --show-cdup); sed -i "s#\(includecode2\?:: \)/../../#\1$up../../#" $file; done
* Move Java and Scala example code to src/test/{java,scala}
> git mv docs/rst/java/code docs/src/test/java
> find docs/rst/java/ -name "*.rst" | xargs sed -i 's#/code/#/../../../test/java/#'
> git mv docs/rst/scala/code docs/src/test/scala
> find docs/rst/scala/ -name "*.rst" | xargs sed -i 's#/code/#/../../../test/scala/#'
* Remove stylistic rst-class directives
* Replace multiple snippets per lines with shared snippet
* =doc Migrate docs from Sphinx to Paradox
Converts .rst files to .md in a best effor way using:
- https://github.com/jonas/akkadocs-sphinx2paradox
References akka#1
* =doc Improve conversion of routing DSL and client-side API overviews
* Fix the docs build
Broken by moving example code to docs/src/test in 926a3b8
* Fixup: Apply docFormatSettings and revert some debug build code
* Minor improvements to @@toc rendering and fix included config files having type=none
Manage HTTP/2 TCK dependencies with sbt
Manage HTTP/2 TCK dependencies with sbt
We want to move documentation from:
To this repo. Both text and tests of course.
The docs should be generated using https://github.com/lightbend/paradox which will allow us to "aggregate" them together with other akka docs into an "aggregated view" if someone wants that.
Otherwise the docs will be separate so this will allow more focused browsing and searching.
The theme for now can be the plain Akka one, though we'll likely want to differentiate a little bit, maybe just by adding HTTP in the header or sth.
I will attempt to make the first step of this move, and then would like to ask for help migrating all the docs to paradox.
The text was updated successfully, but these errors were encountered: