Merge pull request #49 from ikarenkov/docs-site-setup

Docs site setup

.github/workflows/build-docs.yml

@@ -0,0 +1,68 @@
+name: Build documentation
+
+on:
+  push:
+    branches: ["dev"]
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+  pages: write
+
+env:
+  INSTANCE: 'Writerside/modo-docs'
+  ARTIFACT: 'webHelpMODO-DOCS2-all.zip'
+  DOCKER_VERSION: '241.15989'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Build docs using Writerside Docker builder
+        uses: JetBrains/writerside-github-action@v4
+        with:
+          instance: ${{ env.INSTANCE }}
+          artifact: ${{ env.ARTIFACT }}
+          docker-version: ${{ env.DOCKER_VERSION }}
+
+      - name: Save artifact with build results
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: |
+            artifacts/${{ env.ARTIFACT }}
+          retention-days: 7
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    # Requires build job results
+    needs: build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Download artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: docs
+
+      - name: Unzip artifact
+        run: unzip -O UTF-8 -qq ${{ env.ARTIFACT }} -d dir
+
+      - name: Setup Pages
+        uses: actions/[email protected]
+
+      - name: Upload artifact
+        uses: actions/[email protected]
+        with:
+          path: dir
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/[email protected]

Writerside/c.list

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE categories
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/categories.dtd">
+<categories>
+    <category id="wrs" name="Writerside documentation" order="1"/>
+</categories>

Writerside/cfg/buildprofiles.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<buildprofiles xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/build-profiles.xsd"
+               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+
+    <build-profile instance="modo-docs">
+        <variables>
+            <noindex-content>false</noindex-content>
+        </variables>
+    </build-profile>
+
+</buildprofiles>

Writerside/cfg/glossary.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE terms SYSTEM "https://resources.jetbrains.com/writerside/1.0/glossary.dtd">
+<terms>
+    <term name="parcelize">The kotlin-parcelize plugin provides a Parcelable implementation generator. When you annotate a class with @Parcelize, a
+        Parcelable implementation is automatically generated.
+    </term>
+    <term name="StackTransitionType">The enum class that contains Push, Pop, Replace and Idle transition types.</term>
+</terms>

Writerside/codeSnippets/ModoFragment.kt

@@ -0,0 +1,14 @@
+class ModoFragment : Fragment() {
+    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View =
+        ComposeView(inflater.context).apply {
+            setViewCompositionStrategy(ViewCompositionStrategy.DisposeOnViewTreeLifecycleDestroyed)
+            setContent {
+                Column {
+                    val rootScreen = rememberRootScreen {
+                        SampleStack(MainScreen(screenIndex = 1, canOpenFragment = true))
+                    }
+                    rootScreen.Content(modifier = Modifier.fillMaxSize())
+                }
+            }
+        }
+}

Writerside/codeSnippets/ModoManualIntegrationActivity.kt

@@ -0,0 +1,30 @@
+class ModoManualIntegrationActivity : AppCompatActivity() {
+
+    private var rootScreen: RootScreen<StackScreen>? = null
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        WindowCompat.setDecorFitsSystemWindows(window, false)
+        rootScreen = Modo.getOrCreateRootScreen(savedInstanceState, rootScreen) {
+            SampleStack(MainScreen(1))
+        }
+        setContent {
+            ActivityContent {
+                rootScreen?.Content(Modifier.fillMaxSize())
+            }
+        }
+    }
+
+    override fun onSaveInstanceState(outState: Bundle) {
+        Modo.save(outState, rootScreen)
+        super.onSaveInstanceState(outState)
+    }
+
+    override fun onDestroy() {
+        super.onDestroy()
+        if (isFinishing) {
+            Modo.onRootScreenFinished(rootScreen)
+        }
+    }
+
+}

Writerside/codeSnippets/QuickStartActivity.kt

@@ -0,0 +1,14 @@
+class QuickStartActivity : AppCompatActivity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContent {
+            // Remember root screen using rememberSeaveable under the hood.
+            val rootScreen = rememberRootScreen {
+                DefaultStackScreen(StackNavModel(SampleScreen(screenIndex = 1)))
+            }
+            rootScreen.Content(modifier = Modifier.fillMaxSize())
+        }
+    }
+
+}

Writerside/codeSnippets/QuickStartStackScreen.kt

@@ -0,0 +1,29 @@
+@Parcelize
+class QuickStartStackScreen(
+    private val navModel: StackNavModel
+) : StackScreen(navModel) {
+
+    @Composable
+    override fun Content(modifier: Modifier) {
+        TopScreenContent(modifier) { modifier ->
+            ScreenTransition(
+                modifier = modifier,
+                transitionSpec = {
+                    val screenTransitionType = calculateStackTransitionType()
+                    when (screenTransitionType) {
+                        StackTransitionType.Push -> {
+                            slideInHorizontally(initialOffsetX = { it }) togetherWith
+                                slideOutHorizontally(targetOffsetX = { -it })
+                        }
+                        StackTransitionType.Pop -> {
+                            slideInHorizontally(initialOffsetX = { -it }) togetherWith
+                                slideOutHorizontally(targetOffsetX = { it })
+                        }
+                        StackTransitionType.Replace, StackTransitionType.Idle -> fadeIn() togetherWith fadeOut()
+                    }
+                }
+            )
+        }
+    }
+
+}

Writerside/codeSnippets/QuickStartStackScreenContentModification.kt

@@ -0,0 +1,52 @@
+@Parcelize
+class QuickStartStackScreen(
+    private val navModel: StackNavModel
+) : StackScreen(navModel) {
+
+    @Composable
+    override fun Content(modifier: Modifier) {
+        Box(modifier = modifier) {
+            TopScreenContent(
+                Modifier
+                    .background(Color.Cyan)
+                    .padding(16.dp)
+                    .clip(shape = RoundedCornerShape(32.dp))
+                    .fillMaxSize()
+                    .background(Color.White)
+            ) { screenModifier ->
+                ScreenTransition(
+                    modifier = screenModifier,
+                    transitionSpec = {
+                        val screenTransitionType = calculateStackTransitionType()
+                        when (screenTransitionType) {
+                            StackTransitionType.Push -> {
+                                slideInHorizontally(initialOffsetX = { it }) togetherWith
+                                    slideOutHorizontally(targetOffsetX = { -it })
+                            }
+                            StackTransitionType.Pop -> {
+                                slideInHorizontally(initialOffsetX = { -it }) togetherWith
+                                    slideOutHorizontally(targetOffsetX = { it })
+                            }
+                            StackTransitionType.Replace, StackTransitionType.Idle -> fadeIn() togetherWith fadeOut()
+                        }
+                    }
+                )
+            }
+            val context = LocalContext.current
+            IconButton(
+                modifier = Modifier
+                    .align(Alignment.TopEnd)
+                    .padding(8.dp)
+                    .clip(CircleShape)
+                    .background(Color.White),
+                onClick = { context.getActivity()?.finish() }
+            ) {
+                Icon(
+                    painter = rememberVectorPainter(image = Icons.Default.Close),
+                    contentDescription = "Close quick start activity"
+                )
+            }
+        }
+    }
+
+}

Writerside/codeSnippets/SampleScreen.kt

@@ -0,0 +1,40 @@
+// You need to use Parcelize plugin to generate Parcelable implementation for process death survavial
+@Parcelize
+class SampleScreen(
+    // You can pass argiment as a constructor parameter
+    private val screenIndex: Int,
+    // You need to generate a unique screen key using special function
+    override val screenKey: ScreenKey = generateScreenKey()
+) : Screen {
+
+    @Composable
+    override fun Content(modifier: Modifier) {
+        // Taking a nearest stack navigation container
+        val stackNavigation = LocalStackNavigation.current
+        SampleScreenContent(
+            modifier = modifier,
+            screenIndex = screenIndex,
+            openNextScreen = { stackNavigation.forward(SampleScreen(screenIndex + 1)) },
+        )
+    }
+}
+
+@Composable
+private fun SampleScreenContent(
+    modifier: Modifier = Modifier,
+    screenIndex: Int,
+    openNextScreen: () -> Unit,
+) {
+    Column(
+        modifier,
+        verticalArrangement = Arrangement.Center,
+        horizontalAlignment = CenterHorizontally
+    ) {
+        Text(text = "Hello, Modo! Screen №$screenIndex")
+        Button(
+            onClick = openNextScreen
+        ) {
+            Text(text = "Next screen")
+        }
+    }
+}

Writerside/modo-docs.tree

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE instance-profile
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">
+
+<instance-profile name="Modo docs" id="modo-docs" start-page="ModoOverview.md">
+
+    <toc-element topic="ModoOverview.md" />
+    <toc-element topic="QuickStartGuide.md" />
+    <toc-element topic="Core-concepts.md" />
+    <toc-element topic="Modo-and-DI.md" />
+    <toc-element topic="How-to-integrate-modo-to-your-app.md" />
+    <toc-element topic="Community-and-contribution.md" />
+</instance-profile>

Writerside/topics/Community-and-contribution.md

@@ -0,0 +1,3 @@
+# Community and contribution
+
+[//]: # (TBD)

Writerside/topics/Core-concepts.md

@@ -0,0 +1,27 @@
+# Core concepts
+
+Modo is a state-based navigation library for jetpack compose. It represents UI as a structure of `Screen`s and `ContainerScreen`s (which is an
+implementation of `Screen`).
+
+![diagram_1.png](diagram_1.png){ height = 400 }
+
+## Container Screen
+
+Container Screens are the type of screens that can contain other screens. The most used container screen is `StackScreen` that represents a stack of
+screens and renders the last one.
+
+![diagram_2.png](diagram_2.png){ height = 300 }
+
+To render nested screens inside a container screen, you **must** use `InternalContent` function. This function provides all necessary integrations,
+like:
+
+* Correct work of `rememberSaveable` inside nested screens by using `SaveableStateHolder`
+* `ScreenModel`'s integration, that should be the same for the same screen and be cleared when `Screen` leaves the hierarchy
+* Android integration, like `Lifecycle` and `ViewModel` support
+
+Build-in `StackScreen` and `MultiScreen` uses `InternalContent` under the hood, to provide correct work of nested screens.
+
+## Root Screen
+
+To integrate Modo into your application, you use one of the build-in functions from Modo file. It returns a `RootScreen`, that simply provides
+a `SaveableStateHolder`.