Consolidate java/scala content in akka-http #1290
Labels
help wanted
Identifies issues that the core team will likely not have time to work on
t:docs
Issues related to the documentation
Milestone
Comments
|
Let me know which one you want to work on, and I'll mark your name for the file! Under docs/src/main/paradox/java/http/
Directives:
|
|
Thanks a lot @richard-imaoka for getting this initiative started. I think we might want to exclude the directives details pages for now. One reason is that they don't all map 1-to-1 and the other is that the other documentation is currently more important to be merged. |
jrudolph
added
2 - pick next
|
OK sure, removed the directives details pages. |
|
👍, thanks. Let's start with the other ones. |
|
What if a whole section should be on the Scala version but not on the Java one (or vice-versa)? What's the way to do it? |
|
@jlprat Unfortunately we don't have a way to make ToC elements conditional yet, see lightbend/paradox#128 |
|
OK, from the top of my head, there are a couple of pages where some sections are missing on Java (custom headers for example) |
|
Yes, there will probably some difficulties but that shouldn't stop us from starting the work on the easier cases. |
|
Indeed! I will take one of them later today
…On Thu, Jul 20, 2017, 15:33 Johannes Rudolph ***@***.***> wrote:
Yes, there will probably some difficulties but that shouldn't stop us from
starting the work on the easier cases.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#1290 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/ADLuC-tkW7ybqPJF-jGzs_L7tdG4gsOKks5sP1dDgaJpZM4OcKB5>
.
|
|
I take |
jlprat
added a commit
to jlprat/akka-http
that referenced
this issue
Jul 20, 2017
Issue: 1290 Merge Java and Scala doc pages
raboof
pushed a commit
that referenced
this issue
Jul 21, 2017
This was referenced Jul 21, 2017
jonas
added a commit
to jonas/akka-http
that referenced
this issue
Jul 21, 2017
jonas
added a commit
to jonas/akka-http
that referenced
this issue
Jul 21, 2017
jonas
added a commit
to jonas/akka-http
that referenced
this issue
Jul 21, 2017
jonas
added a commit
to jonas/akka-http
that referenced
this issue
Jul 21, 2017
|
Did
|
jonas
added a commit
to jonas/akka-http
that referenced
this issue
Jul 26, 2017
Paradox does not verify them which makes them hard to maintain and
removing them will make it easier to merge the Java and Scala
documentation by avoiding to need to fix a lot of additional anchors.
Generated with:
anchors=$(find docs/src/main/paradox/ -name "*.md" | xargs -n 1 head -1 | sed -n 's#<a id="\(.*\)"></a>#\1#p')
files=$(find docs/src/main/paradox/ -name "*.md")
# Remove fragments from links
for id in $anchors; do sed -i "s/#$id[)]/)/" $files; done
# Remove top-level page anchors
for id in $anchors; do sed -i "/^<a.id=.$id.><.a>$/d" $files; done
raboof
pushed a commit
that referenced
this issue
Jul 26, 2017
* Remove executable bit from .gitignore * =doc #1290 Remove custom anchors at the start of the page Paradox does not verify them which makes them hard to maintain and removing them will make it easier to merge the Java and Scala documentation by avoiding to need to fix a lot of additional anchors. Generated with: anchors=$(find docs/src/main/paradox/ -name "*.md" | xargs -n 1 head -1 | sed -n 's#<a id="\(.*\)"></a>#\1#p') files=$(find docs/src/main/paradox/ -name "*.md") # Remove fragments from links for id in $anchors; do sed -i "s/#$id[)]/)/" $files; done # Remove top-level page anchors for id in $anchors; do sed -i "/^<a.id=.$id.><.a>$/d" $files; done
|
I wrote a small script to help track status and to do the initial work of merging a page: |
|
The 2 last ones ( |
|
@jlprat Is the plan to move the Scala pages into the |
raboof
pushed a commit
that referenced
this issue
Sep 18, 2017
ktoso
pushed a commit
that referenced
this issue
Oct 27, 2017
|
Thanks @atiqsayyed for handling |
This was referenced Dec 6, 2017
|
Cool! I will take a look!
…On Wed, Dec 6, 2017, 15:17 Arnout Engelen ***@***.***> wrote:
@jlprat <https://github.com/jlprat> I think I found a nice solution for
java/scala-specific ToC entries, #1600
<#1600>
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#1290 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/ADLuC-Zwoi3Y5yOCixblZQwucSaPIkRcks5s9qIPgaJpZM4OcKB5>
.
|
jonas
added a commit
to jonas/akka-http
that referenced
this issue
Dec 7, 2017
|
Just about there for the 'regular' documentation, seems like it's time to start tackling the directives now. I've already scripted some common differences in #1608, but there's plenty left - I've added them to the list above. |
Merged
raboof
pushed a commit
that referenced
this issue
Dec 8, 2017
|
@raboof I suggest to close this ticket and track consolidation of the routing DSL docs in a new ticket since the history is getting quite long. |
|
@jonas works for me! @richardimaoka you want to help keep inventory of progress again? |
|
@richardimaoka did you see the ping above? :) |
|
Sorry I misses the earlier message. I didn’t fully go thorough the conversation in detail but it’s about closing this issue and open a new one? Fine for me then. |
|
@richardimaoka Indeed! Do you want to create the ticket again? |
|
What's the most recent status? Is it tracked in #1290 (comment), or should I run @jonas's script to check the status? |
|
I think that comment should be accurate - I haven't run the script myself |
|
OK, here you go ! #1624 |
jonas
removed
2 - pick next
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Like we are doing on akka/akka#23052 "consolidate java/scala content", let's consolidate the java and scala contents in akka-http, too.
Below is the procedure described by @raboof.
The process is as follows:
docs/src/main/paradox/java/...with the same one underdocs/src/main/paradox/scala/....They should cover the same contents, but one is for Java and the other is for Scala. The 'compare files' feature of IntelliJ IDEA is a nice tool for this.scalafolder to contain both the Scala and Java content. You may use:@scalaand@javadirectives for inline text@@@ div { .group-scala }for blockscode blocks become tabbed
git rm akka-docs/src/main/paradox/java/...)cd akka-docs/src/main/paradox/java; ln -s ../scala/... ...; cd -)git add akka-docs/src/main/paradox/java/...)Test your changes (
sbt akka-docs/paradox, see CONTRIBUTING.md for details, check both the Java and Scala versions)You could look at https://github.com/akka/akka/pull/23039/files as an example - it's probably best to contribute PR's on a page-per-page basis at least at first. Feel free to let us know if you have any questions/problems!
The text was updated successfully, but these errors were encountered: