Merge pull request #2699 from illarionov/fixDoc

Various documentation fixes

README.md

@@ -25,7 +25,7 @@ Protocol Buffers
 
  * It's focused. Proto schemas describe your data models. That's it.
 
-<details>
+<details markdown="1">
 <summary>Protocol Buffer Examples</summary>
 
 Here's a [sample message][dinosaur_proto] definition:
@@ -137,7 +137,7 @@ That said, there are some interesting design decisions in Wire:
    due to schema evolution: if tomorrow we add a `carnivore` boolean to our message definition,
    today's data won’t have a value for that field.
 
-<details>
+<details markdown="1">
 <summary>Generated Java Code</summary>
 
 Here's the compact [generated code][dinosaur_java] for the `Dinosaur` message defined above:
@@ -350,7 +350,7 @@ how we used Kotlin to model Protocol Buffers messages:
    * `emptyList()` for `repeated` fields,
    * `emptyMap()` for `map` fields.
 
-<details>
+<details markdown="1">
 <summary>Generated Kotlin Code</summary>
 
 Here's the compact [generated code][dinosaur_kotlin] for the `Dinosaur` message defined above:
@@ -555,7 +555,7 @@ Here's how we used Swift to model Protocol Buffers messages:
  * The nullability of each field's type depends on its label: `required`, `repeated` and `map`
    fields get non-nullable types, whereas `optional` fields are of nullable types.
 
-<details>
+<details markdown="1">
 <summary>Generated Swift Code</summary>
 
 Here's the compact [generated code][dinosaur_swift] for the `Dinosaur` message defined above:
@@ -801,8 +801,8 @@ See [Google's excellent documentation][schema_docs] on the structure and syntax
  [compiler_docs_swift]: docs/wire_compiler.md#swift-support
  [grpc_docs]: docs/wire_grpc.md
 
- [dinosaur_proto]: samples/simple-sample/src/main/proto/squareup/dinosaurs/dinosaur.proto
- [period_proto]: samples/simple-sample/src/main/proto/squareup/geology/period.proto
- [dinosaur_java]: samples/simple-sample/src/main/java/com/squareup/dinosaurs/Sample.java
- [dinosaur_kotlin]: wire-tests/src/commonTest/proto-kotlin/com/squareup/dinosaurs/Dinosaur.kt
- [dinosaur_swift]: wire-runtime-swift/src/test/swift/sample/Dinosaur.swift
+ [dinosaur_proto]: https://github.com/square/wire/blob/master/samples/simple-sample/src/main/proto/squareup/dinosaurs/dinosaur.proto
+ [period_proto]: https://github.com/square/wire/blob/master/samples/simple-sample/src/main/proto/squareup/geology/period.proto
+ [dinosaur_java]: https://github.com/square/wire/blob/master/samples/simple-sample/src/main/java/com/squareup/dinosaurs/Sample.java
+ [dinosaur_kotlin]: https://github.com/square/wire/blob/master/wire-tests/src/commonTest/proto-kotlin/com/squareup/dinosaurs/Dinosaur.kt
+ [dinosaur_swift]: https://github.com/square/wire/blob/master/wire-runtime-swift/src/test/swift/sample/Dinosaur.swift

deploy_website.sh

@@ -25,10 +25,10 @@ cd $DIR
 
 # Fix *.md links to point to where the docs live under Mkdocs.
 # Linux
-# sed -i 's/docs\/wire_compiler.md/wire_compiler/' README.md
+# sed -i 's/docs\/wire_compiler.md/wire_compiler.md/' README.md
 # OSX
-sed -i "" 's/docs\/wire_compiler.md/wire_compiler/' README.md
-sed -i "" 's/docs\/wire_grpc.md/wire_grpc/' README.md
+sed -i "" 's/docs\/wire_compiler.md/wire_compiler.md/' README.md
+sed -i "" 's/docs\/wire_grpc.md/wire_grpc.md/' README.md
 
 # Copy in special files that GitHub wants in the project root.
 cat README.md | grep -v 'project website' > docs/index.md

docs/wire_compiler.md

@@ -385,22 +385,22 @@ Here's an exhaustive Java configuration. Booleans are shown with their default b
 wire {
   java {
     // Proto types to include generated sources for. Types listed here will be
-    // generated for this/ target and not for subsequent targets in the task.
+    // generated for this target and not for subsequent targets in the task.
     //
-    // This list should contain package names (suffixed with `.*`) and type names
-    // only. It should not contain member names.
+    // This list should contain package names (suffixed with `.*`) and type
+    // names only. It should not contain member names.
     includes = ['com.example.pizza.*']
 
-    // Proto types to excluded generated sources for. Types listed here will not
-    // be generated for this target.
+    // Proto types to excluded generated sources for. Types listed here will
+    // not be generated for this target.
     //
-    // This list should contain package names (suffixed with `.*`) and type names
-    // only. It should not contain member names.
+    // This list should contain package names (suffixed with `.*`) and type
+    // names only. It should not contain member names.
     excludes = ['com.example.sales.*']
 
-    // True if types emitted for this target should not also be emitted for other
-    // targets. Use this to cause multiple outputs to be emitted for the same input
-    // type.
+    // True if types emitted for this target should not also be emitted for
+    // other targets. Use this to cause multiple outputs to be emitted for the
+    // same input type.
     exclusive = true
 
     // Directory to emit to.
@@ -409,14 +409,16 @@ wire {
     // True for emitted types to implement android.os.Parcelable.
     android = false
 
-    // True to enable the androidx.annotation.Nullable annotation where applicable.
+    // True to enable the androidx.annotation. Nullable annotation
+    // where applicable.
     androidAnnotations = false
 
     // True to emit code that uses reflection for reading, writing, and toString
     // methods which are normally implemented with generated code.
     compact = false
 
-    // True to turn visibility of all generated types' constructors to non-public.
+    // True to turn visibility of all generated types' constructors
+    // to non-public.
     buildersOnly = false
 
     // True to emit types for options declared on messages, fields, etc.
@@ -436,22 +438,22 @@ Here's an exhaustive Kotlin configuration. Booleans and enums are shown with the
 wire {
   kotlin {
     // Proto types to include generated sources for. Types listed here will be
-    // generated for this/ target and not for subsequent targets in the task.
+    // generated for this target and not for subsequent targets in the task.
     //
-    // This list should contain package names (suffixed with `.*`) and type names
-    // only. It should not contain member names.
+    // This list should contain package names (suffixed with `.*`) and type
+    // names only. It should not contain member names.
     includes = ['com.example.pizza.*']
 
     // Proto types to excluded generated sources for. Types listed here will not
     // be generated for this target.
     //
-    // This list should contain package names (suffixed with `.*`) and type names
-    // only. It should not contain member names.
+    // This list should contain package names (suffixed with `.*`) and type
+    // names only. It should not contain member names.
     excludes = ['com.example.sales.*']
 
-    // True if types emitted for this target should not also be emitted for other
-    // targets. Use this to cause multiple outputs to be emitted for the same input
-    // type.
+    // True if types emitted for this target should not also be emitted for
+    // other targets. Use this to cause multiple outputs to be emitted for the
+    // same input type.
     exclusive = true
 
     // Directory to emit to.
@@ -460,11 +462,12 @@ wire {
     // True for emitted types to implement android.os.Parcelable.
     android = false
 
-    // True for emitted types to implement APIs for easier migration from the Java
-    // target.
+    // True for emitted types to implement APIs for easier migration from the
+    // Java target.
     javaInterop = false
 
-    // True to turn visibility of all generated types' constructors to non-public.
+    // True to turn visibility of all generated types' constructors
+    // to non-public.
     buildersOnly = false
 
     // True to emit types for options declared on messages, fields, etc.
@@ -473,7 +476,8 @@ wire {
     // True to emit annotations for options applied on messages, fields, etc.
     emitAppliedOptions = true
 
-    // `suspending` to generate coroutines APIs that require a Kotlin coroutines context.
+    // `suspending` to generate coroutines APIs that require a Kotlin
+    // coroutines context.
     // `blocking` to generate blocking APIs callable by Java and Kotlin.
     rpcCallStyle = 'blocking'
 
@@ -482,8 +486,8 @@ wire {
     // `none` to not generate services.
     rpcRole = 'server'
 
-    // If set, the value will be appended to generated service type names. If null, their rpcRole
-    // will be used as a suffix instead.
+    // If set, the value will be appended to generated service type names. If
+    // null, their rpcRole will be used as a suffix instead.
     nameSuffix = "Suffix"
 
     // True for emitted services to implement one interface per RPC.
@@ -628,9 +632,9 @@ LightSideProtos:
     - jedi.Lightning
 ```
 
- [SchemaHandler.Factory]: /wire-schema/src/commonMain/kotlin/com/squareup/wire/schema/SchemaHandler.kt#L192
- [SchemaHandlerRecipes]: /wire-schema-tests/src/test/java/com/squareup/wire/recipes
- [SchemaHandler]: /wire-schema/src/commonMain/kotlin/com/squareup/wire/schema/SchemaHandler.kt
+ [SchemaHandler.Factory]: https://github.com/square/wire/blob/master/wire-schema/src/commonMain/kotlin/com/squareup/wire/schema/SchemaHandler.kt#L194
+ [SchemaHandlerRecipes]: https://github.com/square/wire/tree/master/wire-schema-tests/src/commonTest/kotlin/com/squareup/wire/recipes
+ [SchemaHandler]: https://github.com/square/wire/blob/master/wire-schema/src/commonMain/kotlin/com/squareup/wire/schema/SchemaHandler.kt
 
  [gradle]: https://gradle.org/
  [kotlinpoet]: https://github.com/square/kotlinpoet

mkdocs.yml

@@ -23,6 +23,7 @@ markdown_extensions:
   - codehilite:
       guess_lang: false
   - footnotes
+  - md_in_html
   - meta
   - toc:
       permalink: true
@@ -63,3 +64,6 @@ nav:
   - 'Code of Conduct': code_of_conduct.md
   - 'Protocol Buffers ⏏': https://developers.google.com/protocol-buffers/docs/proto
 
+not_in_nav: |
+  security.md
+  3.x/**