Commit 206ea828 authored by garciadeblas's avatar garciadeblas
Browse files

feat: restructure user guide following Diataxis information architecture



Reorganise all documentation into Diataxis-aligned folders (getting-started,
tutorial, explanation, how-to, how-to/nfv, reference, developer-guide, others).
Each folder has its own index.rst for the Sphinx toctree hierarchy. Large source
files (05-osm-usage, 04-vim-setup, 06-advanced-cluster-management) are split into
topic-focused how-to guides. Developer guide content is sourced from the
feat/gitlab-workflow branch of osm-developer-guide. All internal cross-links and
image paths updated to reflect new folder depths.

Co-Authored-By: default avatarClaude Sonnet 4.6 <noreply@anthropic.com>
parent cc6cc8fb
Loading
Loading
Loading
Loading
Loading

08-what-to-read-next.md

deleted100644 → 0
+0 −13
Original line number Diff line number Diff line
# What to read next

[latest-hackfest]: https://osm.etsi.org/wikipub/index.php/Latest_OSM_Hackfest_Material#Hackfest_Material
[developer-guide]: https://osm.etsi.org/docs/developer-guide/

If you want to learn more, these additional contents are highly recommended:

- **[VNF Onboarding Guide](https://osm.etsi.org/docs/vnf-onboarding-guidelines).** This guide includes all that you might need to onboard your VNF or applications in OSM.
- **[OSM Developer Guide][developer-guide].** If you want to contribute to OSM development, it is highly recommended reading this guide first.
- **[Sample VNF Packages](https://osm.etsi.org/gitlab/vnf-onboarding/osm-packages.git).**
- **[Contents from latest edition of OSM Hackfest][latest-hackfest].**
- [OSM Workshops and Webinars](https://osm.etsi.org/wikipub/index.php/OSM_workshops_and_events)
- [Release notes and white papers](https://osm.etsi.org/wikipub/index.php/Release_notes_and_whitepapers)

CLAUDE.md

0 → 100644
+158 −0
Original line number Diff line number Diff line
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Purpose

This is the **OSM User Guide**, a Sphinx-based documentation site published at https://osm.etsi.org/docs/user-guide/. It covers installation, usage, architecture, VIM setup, cluster management, CLI reference, and troubleshooting for all active OSM releases.

## Build Commands

```bash
# Build versioned HTML (output: _build/html/)
tox -e build

# Live preview with auto-rebuild on port 8001
tox -e run

# Publish to ETSI FTP (requires credentials in local/.credentials)
tox -e publish

# Publish to the test location on ETSI FTP
tox -e test-publish
```

`tox -e build` runs `sphinx-multiversion`, which generates a separate HTML subtree for every release branch (`v10``v19`) plus `develop` and `latest`. It also runs `fix_cross_references.sh` afterwards to patch Sphinx's incorrect `.md``.html` link conversion.

For `tox -e publish`, credentials must be stored in `local/.credentials` with `USERNAME=` and `PASSWORD=` lines. That file is gitignored.

## Repository Structure

The guide follows the **Diataxis** information architecture, organised into topic folders. Each folder has its own `index.rst` for the Sphinx toctree hierarchy.

```
osm-user-guide/
├── index.rst                  # Sphinx master toctree (hierarchical, folder-based)
├── index.md                   # Navigation reference (excluded from Sphinx)
├── navigation.md              # Quick-nav links (excluded from Sphinx)
├── conf.py                    # Sphinx configuration
├── Makefile
├── tox.ini                    # Build environments: build, run, publish, test-publish
├── requirements.txt           # Sphinx + plugins pinned versions
├── _static/                   # CSS and images
├── _templates/                # Jinja2 templates (layout, topbar, versions)
├── assets/                    # Diagram images (PNG, JPG)
├── fix_cross_references.sh    # Post-build: fixes .md → .html links
├── updater.sh                 # Bulk version number updates across all files
├── upload_doc.sh              # FTP upload helper used by tox publish
├── .gitlab-ci.yml             # CI: builds on every push, publishes on protected branches

├── getting-started/
│   ├── index.rst
│   └── quickstart.md

├── tutorial/
│   ├── index.rst
│   ├── charmed-osm-cnf.md
│   └── k8s-declarative-framework.md

├── explanation/
│   ├── index.rst
│   ├── architecture.md
│   └── service-assurance.md

├── how-to/
│   ├── index.rst
│   ├── installing-osm.md
│   ├── managing-vim-accounts.md
│   ├── managing-k8s-clusters.md
│   ├── managing-profiles.md
│   ├── managing-oka.md
│   ├── managing-ksu.md
│   ├── managing-app-instances.md
│   ├── managing-users-projects-roles.md
│   ├── troubleshooting.md
│   ├── upgrading-osm.md
│   ├── running-tests.md
│   ├── openvim-installation.md
│   ├── k8s-installation.md
│   ├── lxd-cluster.md
│   ├── tacacs-authentication.md
│   ├── preparing-git-repos-flux.md
│   └── nfv/
│       ├── index.rst
│       ├── managing-vnf-ns-packages.md
│       ├── deploying-network-services.md
│       ├── operating-network-services.md
│       ├── scaling-network-services.md
│       ├── healing-network-services.md
│       ├── monitoring-network-services.md
│       ├── network-slices.md
│       └── sdn-wim.md

├── reference/
│   ├── index.rst
│   ├── client-commands.md
│   ├── information-model.md
│   ├── nbi-api.md
│   ├── releases.md
│   ├── architecture-ref.md
│   ├── declarative-framework.md
│   ├── packages.md
│   └── naming-conventions.md

├── developer-guide/
│   ├── index.rst
│   ├── 01-workflow-osm-tools.md
│   ├── 02-developer-how-to.md
│   ├── 03-developer-how-to-for-modules.md
│   ├── 04-merge-conflicts.md
│   ├── 05-git-review.md
│   └── 06-testing-before-committing.md

└── others/
    ├── index.rst
    ├── faq.md
    └── contributing-to-docs.md
```

## Source Format

All content is written in **Markdown** (`.md`). Each folder also has an `index.rst` (RST format) to provide Sphinx toctree entries for that section. Both formats are supported via `recommonmark`.

## Image Paths

Images live in `assets/` at the repo root. Use relative paths from the document's location:
- Files in top-level folders (e.g. `how-to/`): `../assets/image.png`
- Files two levels deep (e.g. `how-to/nfv/`): `../../assets/image.png`

## Versioning

The guide is versioned per OSM release branch. `sphinx-multiversion` builds all branches matching the patterns in `conf.py`:

```python
smv_branch_whitelist = r'(v19|v18|v17|...|v10)'
smv_tag_whitelist    = r'(latest|develop)'
```

Each version is published under `/versions/<branch>/` on the ETSI site. When working on documentation for a specific release, check out the corresponding branch (e.g. `v19`).

To update version numbers across all files when preparing a new release, use:

```bash
./updater.sh <old_version> <new_version>
```

## CI/CD

`.gitlab-ci.yml` runs two stages:
1. **build-docs** — runs `tox -e build` on every push; HTML output is saved as a CI artifact
2. **deploy-job** — runs only on protected branches; uses `FTP_USERNAME` and `FTP_PASSWORD` CI variables to publish to the ETSI FTP server

## Key Dependencies

- `Sphinx 5.1.1` — documentation builder
- `sphinx-rtd-theme 1.0.0` — Read the Docs theme
- `recommonmark 0.7.1` — Markdown support in Sphinx
- `sphinx-multiversion 0.2.4` — multi-branch versioned builds
- `sphinx-autobuild` — live preview server (used by `tox -e run`)
+1 −1
Original line number Diff line number Diff line
@@ -41,7 +41,7 @@
    </div>
    <div class="topbar-right">
        <a href="https://osm.etsi.org/docs/user-guide/latest/">Docs</a>
        <a href="https://osm.etsi.org/docs/user-guide/latest/03-installing-osm.html">Install</a>
        <a href="https://osm.etsi.org/docs/user-guide/latest/how-to/installing-osm.html">Install</a>
        <a href="https://osm.etsi.org/news-events/news">News & Events</a>
        <div class="dropdown">
            <button>Community</button>
+26.4 KiB
Loading image diff...
+142 KiB (169 KiB)
Loading image diff...
Loading