🛡️ Dokumentoinnin status¶
Dokumentin tilatiedot lisätään jokaisen dokumentin loppuun.
Tilatiedot auttavat sekä kirjoittajaa että lukijaa hahmottamaan dokumentin elinkaaren ja varmistavat, että keskeneräiset tai vanhentuneet ohjeet tunnistetaan helposti.
Käytössä oleva merkintätapa¶
<!-- > Valitse yksi poistamalla kommenttimerkki -->
<!-- > **Dokumentin tila:** Luonnos — Pvm: 01.01.2026 -->
<!-- > **Dokumentin tila:** Työn alla — Pvm: 01.01.2026 -->
<!-- > **Dokumentin tila:** Tarkistettavana — Pvm: 01.01.2026 -->
<!-- > **Dokumentin tila:** Valmis — Pvm: 01.01.2026 -->
<!-- > **Dokumentin tila:** Poistettu käytöstä — Pvm: 01.01.2026 -->
Tuleva kehitys: Automaation ja metadata dokumentaatiossa¶
Tämän kehityssuunnan tavoitteena on ottaa käyttöön yksinkertainen, konfliktiton ja automaatiolle helposti parsittava metadatalohko Markdown‑dokumenttien loppuun.
Lohko mahdollistaa dokumenttien tilan, version ja päivityspäivän automaattisen seurannan.
1. Metadataformaatti¶
Periaatteet
- Lohko alkaa ja päättyy rivillä: +++metadata
- Avain–arvo‑parit ovat YAML‑yhteensopivia
- Lohko sijaitsee aina dokumentin lopussa
Automaation tulee pystyä havaitsemaan: - dokumentin tila - viimeisin päivityspäivä - versio - puuttuva metadata
2. Metadatan lukeminen¶
# tools/metadata_reader.py
import yaml
def read_metadata(path):
with open(path, "r", encoding="utf-8") as f:
lines = f.readlines()
# Etsi metadata-lohkon rajat
indices = [i for i, line in enumerate(lines) if line.strip() == "+++metadata"]
if len(indices) < 2:
return None # metadata puuttuu
start = indices[-2]
end = indices[-1]
block = "".join(lines[start+1:end])
try:
return yaml.safe_load(block)
except Exception:
return None
3. Tilaraportin generointi¶
# tools/generate_report.py
import glob
from metadata_reader import read_metadata
def generate_report():
report_lines = []
report_lines.append("| Tiedosto | Tila | Pvm | Versio |")
report_lines.append("|----------|------|-----|--------|")
for path in glob.glob("docs/**/*.md", recursive=True):
meta = read_metadata(path)
if meta is None:
report_lines.append(f"| {path} | PUUTTUU | PUUTTUU | PUUTTUU |")
else:
report_lines.append(
f"| {path} | {meta.get('tila','PUUTTUU')} | {meta.get('pvm','PUUTTUU')} | {meta.get('versio','PUUTTUU')} |"
)
with open("docs/tilaraportti.md", "w", encoding="utf-8") as f:
f.write("# Dokumenttien tilaraportti\n\n")
f.write("\n".join(report_lines))
if __name__ == "__main__":
generate_report()
4. CI‑validointi¶
validate_metadata:
stage: test
script:
- python tools/generate_report.py
- python tools/validate_metadata.py
allow_failure: false
Validointiskripti¶
# tools/validate_metadata.py
import glob
from metadata_reader import read_metadata
import sys
errors = []
for path in glob.glob("docs/**/*.md", recursive=True):
if read_metadata(path) is None:
errors.append(path)
if errors:
print("Seuraavista dokumenteista puuttuu metadata:")
for e in errors:
print(" -", e)
sys.exit(1)
print("Kaikissa dokumenteissa on metadata.")
5. Kehityspolku¶
Vaihe 1 — Standardointi
- Vahvistetaan +++metadata RepoDock‑standardiksi
- Lisätään dokumenttipohjiin
- Päivitetään ohjeistus
Vaihe 2 — Parseri
- Toteutetaan metadata_reader.py
- Testataan eri dokumenteilla
Vaihe 3 — Raportointi
- Toteutetaan generate_report.py
- Raportti tallennetaan docs/tilaraportti.md
Vaihe 4 — CI‑validointi
- Lisätään GitLab CI ‑jobi
- Merge‑pyynnöt estetään vai estetäänkö, jos metadata puuttuu
Vaihe 5 — Laajennukset
- automaattinen versionumeron nosto
- automaattinen päivämäärän päivitys
- dokumenttien elinkaariseuranta
6. Lopputulos¶
Kun tämä toteutetaan: - dokumenteilla on yhdenmukainen metadata - automaatio tuottaa tilaraportin - puuttuva metadata havaitaan automaattisesti - CI estää ja/tai listaa virheelliset dokumentit - dokumentaatio pysyy aina ajan tasalla
Dokumentin tila: Luonnos — Pvm: 10.01.2026