rewrite docs to vitepress

.gitignore

@@ -13,3 +13,11 @@
 
 # Dependency directories (remove the comment below to include it)
 # vendor/
+
+dist/
+.DS_Store
+docs/.vitepress/cache
+docs/.vitepress/dist
+docs/*.pdf
+docs/node_modules
+

.goreleaser.yaml

@@ -4,6 +4,7 @@ before:
   hooks:
     # You may remove this if you don't use go modules.
     - go mod tidy
+    - sh -c "cd docs && npm ci && npm run export-pdf"
 
 builds:
   - env:
@@ -21,12 +22,14 @@ builds:
         goarch: arm64
 
 release:
+  extra_files:
+    - glob: ./docs/ksef-dokumentacja-uzytkownika.pdf
+
   footer: |
     # :open_file_folder: Files Checksum
     ```
     {{ .Checksums }}
     ```
-
 archives:
   - format: tar.gz
     # this name template makes the OS and Arch compatible with the results of `uname`.
@@ -44,6 +47,8 @@ archives:
     files:
       - przykladowe-pliki-wejsciowe
       - klucze
+      - src: docs/ksef-dokumentacja-uzytkownika.pdf
+        dst: ksef-dokumentacja-uzytkownika.pdf
 
 changelog:
   sort: asc

README.md

@@ -1,123 +1,17 @@
-kompilacja programu:
+# Dokumentacja programu
 
-```
-go build -o ksef ksef/cmd/main.go
-```
-
-w celu rekompilacji schematów (robisz to tylko jeśli chcesz dodać własny schemat oraz generator - fa(2) wymagany przez ministerstwo jest już sparsowany):
-
-```
-go run parse_schemas.go
-```
-
-wówczas program sparsuje schematy z katalogu "schemas" i wygeneruje odpowiednie struktury w katalogu "internal/sei/generators"
-
-Jeśli zastanawiasz się po kiego grzyba jest ten generowany kod spieszę odpowiedzieć, że niestety ministerstwo używa typu sequence a on wymusza aby elementy w drzewie występowały w określonej kolejności (sic!) miałem więc do wyboru albo zaimplementować struktury w ten sposób, żeby ręcznie wklepać je do kodu w golang albo zaimplementować je w sposób ogólniejszy aby to użytkownik programu wypełniał te pola / atrybuty które wie, że potrzebuje (bo zdecydowana większość pól i tak jest pusta / opcjonalna) a program na podstawie sparsowanej schemy posortuje atrybuty według kolejności i XML przejdzie walidację. struktury generowane przez parse_schemas to nic innego jak tylko definicja kolejności w drzewie. po wygenerowaniu faktury mogę przepuścić ją przez funkcję sortującą przesortować elementy drzewa XML tak aby były w takiej kolejności jak w źródłowym pliku .xsd. Oczywiście tu pojawia się pytanie czy trzeba zapisywać stan tego parsowania na dysku - bo teoretycznie można by to robić w locie. Stwierdziłem, źe po pierwsze nie chcę marnować mocy procesora a po drugie ta kolejność i tak się przecież nie zmieni - a jeśli się zmieni to i tak będzie to nowy schemat, prawdopodobnie z nowym plikiem .xsd
-
-## zapis tokenu
-
-przesyłanie faktur poprzez sesję wsadową jest dość uciążliwe ponieważ wymaga ono każdorazowego podpisu paczki faktur, co w przypadku korzystania z bramki e-obywatel / profil zaufany powoduje generowanie kilku wiadomości SMS. Aby tego uniknąć KSeF przewidział sesję interaktywną. Po zalogowaniu się do aplikacji można tam wygenerować token. Następnie należy uzyć komendy `save-token` aby zapisać go do rejestru kluczy systemu operacyjnego.
-
-```bash
-  -nip string
-    	numer NIP podatnika
-  -t	użyj bramki testowej
-  -token string
-    	token wygenerowany na środowisku KSeF
-```
-
-Przykładowe wywołanie
-
-```bash
-./ksef save-token -t -nip 1111111111 -token AAABBBCCC....
-```
-
-Od tej pory, podczas wysyłki faktur, program rozpozna wystawcę faktur (tj. jego numer NIP) i pobierze z rejestru kluczy odpowiedni token
-
-## generowanie faktur:
-
-./ksef generate -d ';' -f faktury.csv -o katalog-docelowy [-t]
-
-(parametr -t uzywa klucza publicznego bramki testowej do generowania metadanych)
-
-## metadane (tylko tryb wsadowy)
-
-```bash
-  -p string
-    	ścieżka do wygenerowanych plików
-  -t	użyj bramki testowej
-```
-
-Jeśli nie chcesz używać tokenu i zamiast tego wolisz przesyłać faktury w sesji wsadowej, musisz najpierw wygenerować plik metadanych a następnie podpisać go.
-
-Przykładowe wywołanie:
-
-```bash
-./ksef metadata -p katalog-z-plikami-faktur [-t]
-```
-
-w katalogu docelowym program stworzy pliki:
-
-- metadata.xml [surowy plik metadanych który należy podpisać. Podpisanego pliku użyjesz w kolejnym kroku (`wysyłka faktur`)]
-- metadata.zip [surowy plik archiwum, nie jest on wysyłany na serwer]
-- metadata.zip.aes [plik archiwum zaszyfrowany odpowiednim kluczem ministerstwa, zależnym od wybranego trybu (testowy / produkcja) - to ten plik jest przesyłany]
-
-### podpisywanie pliku metadanych
-
-Aby podpisać plik metadanych użyj trybu "Osadzonego". Możesz użyć do tego celu karty kryptograficznej lub aplikacji m-obywatel: https://moj.gov.pl/nforms/signer/upload?xFormsAppName=SIGNER&xadesPdf=true. Po podpisaniu dokumentu bramka zwróci plik xml z doklejoną sekcją podpisu (`Signature`). Należy ten plik zapisać i przejść do kolejnego kroku (`wysyłka faktur`):
-
-## wysylka faktur
-
-```bash
-  -i	użyj sesji interaktywnej
-  -p string
-    	ścieżka do katalogu z wygenerowanymi fakturami
-  -sj
-    	użyj formatu JSON do zapisu pliku statusu (domyślnie YAML)
-  -t	użyj bramki testowej
-```
-
-Przewidziane zostały dwa tryby wysyłki faktur.
-
-### tryb wsadowy
-
-Aby skorzystać z trybu wsadowego upewnij się, że podisałeś plik metadanych (patrz sekcja `metadane`). Następnie wywołaj ksef w poniższy sposób:
-
-```bash
-./ksef upload -p podpisany-metadata.xml [-t]
-```
-
-### tryb interaktywny
-
-Aby skorzystać z trybu interaktywnego należy uprzednio wygenerować token na stronie aplikacji KSeF oraz zapisać go do systemowego repozytorium kluczy (patrz sekcja `zapis tokenu`). Następnie wywołujemy ksef w następujący sposób:
-
-```bash
-./ksef upload -i -p katalog-z-plikami-xml [-t]
-```
-
-Niezależnie od wybranego trybu wysyłki, program utworzy plik `status.{yaml,json}` który posłuży do sprawdzenia statusu i pobrania UPO (w przypadku pozytywnego przetworzenia faktur). Domyślny format dla pliku statusu to YAML
-
-## pobieranie upo
-
-```bash
-Usage of status:
-  -o string
-    	ścieżka do zapisu UPO (domyślnie katalog pliku statusu + {nrRef}.pdf)
-  -p string
-    	ścieżka do pliku statusu
-  -xml
-    	zapis UPO jako plik XML
-```
+Dokumentację znajdziesz w katalogu `docs`. Masz kilka możliwości jej odczytania:
 
-Przykładowe wywołanie:
+## Lokalne przebudowanie
 
-```bash
-./ksef status -p sciezka-do-pliku-status.{yaml,json}
+```shell
+cd docs
+npm ci
+npm run docs:dev
 ```
 
-jesli status przetworzenia faktur bedzie poprawny, program pobierze upo i wygeneruje plik:
+Dokumentacja zostanie udostępniona na porcie 5137
 
-- {nrRef}.xml (jesli zostanie wybrany parametr -xml)
-- {nrRef}.pdf (domyślnie)
+## Plik PDF
 
-UPO jest gotowe do druku.
+Przy każdym buildzie programu generowany jest PDF z dokumentacją. Można go znaleźć w środku archiwum oraz w artefaktach buildu

docs/.vitepress/config.mjs

@@ -0,0 +1,40 @@
+import { defineConfig } from 'vitepress'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "klient KSeF",
+  description: "Dokumentacja użytkownika",
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Dokumentacja', link: '/content/' }
+    ],
+
+    sidebar: [
+      {
+        text: 'Instalacja',
+        items: [
+          { text: 'Instalacja programu', link: '/content/instalacja' },
+        ]
+      },
+      {
+        text: 'Komendy',
+        items: [
+          { text: 'Zapisanie tokenu', link: '/content/komendy/save-token'},
+          { text: 'Generowanie faktur', link: '/content/komendy/generate'},
+          { text: 'Wysyłka faktur', items: [
+            {text: 'Sesja wsadowa (batch)', link: '/content/komendy/upload/batch'},
+            {text: 'Sesja interaktywna', link: '/content/komendy/upload/interaktywna'},
+          ]},
+          { text: 'Pobieranie UPO', link: '/content/komendy/upo'},
+          { text: 'Wizualizacja PDF', link: '/content/komendy/wizualizacja-pdf'},
+        ]
+      }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/toudi/ksef' }
+    ]
+  }
+})

docs/.vitepress/theme/index.ts

@@ -0,0 +1,10 @@
+// .vitepress/theme/index.ts
+import DefaultTheme from "vitepress/theme";
+
+// custom CSS
+import "./print.css";
+
+export default {
+	// Extending the Default Theme
+	...DefaultTheme,
+};

docs/.vitepress/theme/print.css

@@ -0,0 +1,7 @@
+@media print {
+	.VPNav,
+	.VPLocalNav,
+	.VPDocFooter {
+		display: none !important;
+	}
+}

docs/content/index.md

@@ -0,0 +1,3 @@
+# Dokumentacja KSeF
+
+Tutaj znajdziesz krótki opis który przeprowadzi Cię przez klienta KSeF

docs/content/docs/instalacja.md → docs/content/instalacja.md

@@ -1,11 +1,6 @@
 ---
 weight: 100
 title: "Instalacja"
-description: ""
-icon: "article"
-date: "2023-12-12T01:42:35+01:00"
-lastmod: "2023-12-12T01:42:35+01:00"
-draft: true
 toc: true
 ---
 

docs/content/docs/komendy/_index.md → docs/content/komendy/_index.md

@@ -1,11 +1,6 @@
 ---
 weight: 999
 title: "Dostępne komendy"
-description: ""
-icon: "article"
-date: "2023-12-12T01:49:22+01:00"
-lastmod: "2023-12-12T01:49:22+01:00"
-draft: true
 toc: true
 ---
 

docs/content/docs/komendy/generate.md → docs/content/komendy/generate.md

@@ -1,13 +1,4 @@
----
-weight: 999
-title: "Generowanie faktur"
-description: ""
-icon: "article"
-date: "2023-12-12T01:49:22+01:00"
-lastmod: "2023-12-12T01:49:22+01:00"
-draft: true
-toc: true
----
+# Generowanie faktur
 
 W tym rozdziale zajmiemy się generowaniem faktur. Program obsługuje kilka formatów plików wejściowych.
 
@@ -30,11 +21,15 @@ Usage of generate:
 
 ## Uwagi techniczne
 
-{{< alert context="info" text="Kolejność pól nie ma znaczenia. Program podczas konwersji sortuje pola według schematu przewidzianego przez ministerstwo." />}}
+::: info
+Kolejność pól nie ma znaczenia. Program podczas konwersji sortuje pola według schematu przewidzianego przez ministerstwo
+:::
 
-{{< alert context="info" text="Większość z pól przewidzianych przez ministerstwo i tak jest opcjonalna więc w plikach źródłowych uzupełniaj tylko te których potrzebujesz" />}}
+::: info
+Większość z pól przewidzianych przez ministerstwo i tak jest opcjonalna więc w plikach źródłowych uzupełniaj tylko te których potrzebujesz
+:::
 
-{{% alert context="info" %}}
+::: info
 Korzystaj z mnemoników. Zamiast mało przyjaznych nazw pól takich jak `P_7`, `P_12` możesz posłużyć się mnemonikami które program w locie przetłumaczy na oczekiwane przez ministerstwo:
 
 | mnemonik         | pole | znaczenie               |
@@ -46,7 +41,7 @@ Korzystaj z mnemoników. Zamiast mało przyjaznych nazw pól takich jak `P_7`, `
 | unit-price-gross | P_9B | Cena jednostkowa brutto |
 | vat-rate         | P_12 | Stawka VAT              |
 
-{{% /alert %}}
+:::
 
 ## CSV z sekcjami
 
@@ -64,7 +59,7 @@ Przykłady wywołania:
 ./ksef generate -f plik.csv -d ';' -o katalog-wyjsciowy
 ```
 
-{{% alert context="info" %}}
+::: info
 Jeśli Twój system wejściowy zapisuje kwoty za pomocą liczb całkowitych, możesz je równiez w ten sposób wyeksportować. W tym celu oprócz wyeksportowania wartości w wybranym przez Ciebie polu utwórz kolejne z dopiskiem `.decimal-places` i wstaw tam mnożnik. Dla przykładu, zapis:<br />
 
 ```
@@ -82,7 +77,7 @@ podczas gdy zapis
 ```
 
 Oznaczać będzie liczbę `0.0123`
-{{% /alert %}}
+:::
 
 ## XLSX / Excell 2007+ / Libreoffice
 
@@ -92,7 +87,7 @@ Ten format przewidziałem dla integracji gdzie źródłem danych są faktury wys
 
 Tu dochodzimy do formatu gdzie integracja najprawdopodobniej umożliwia zastosowanie biblioteki generującej dane wyjściowe
 
-{{% alert context="info" %}}
+::: info
 YAML umożliwia zapisywanie liczb zmiennoprzecinkowych. Tym niemniej, bezpieczniejszym sposobem może być albo wyeksportowanie kwoty jako string albo w formie bazowej. Sprowadzając rzecz do konkretów, kwotę `1.23` możesz zapisać w następujące sposoby:
 
 ```yaml
@@ -109,4 +104,4 @@ unit-price-net:
   decimal-places: 2
 ```
 
-{{% /alert %}}
+:::