Git Product home page Git Product logo

swh-docs's Introduction

swh-docs

This module contains (the logics for generating) the Software Heritage development documentation.

Specifically, it contains some general information about Software Heritage internals (stuff that would not fit in any other specific software component of the Software Heritage stack) and bundle them together component-specific documentation coming from other modules of the stack.

All documentation is written and typeset using Sphinx. General documentation is shipped as part of this module. Module-specific documentation is centralized here via symlinks to the docs/ dirs of individual modules. Therefore to build the full documentation you need a working and complete Software Heritage development environment.

How to build the doc

Install the Software Heritage development environment

$ git clone https://forge.softwareheritage.org/source/swh-environment
$ cd swh-environment
$ ./bin/update  # this will clone needed git repos, inc. swh-docs
$ cd swh-docs

Ensure you have the required tools to generate images (graphviz's dot and plantuml). On a Debian system:

$ sudo apt install plantuml graphviz

It is also recomanded to build the doc using tox, so ensure you have it installed, eg. on a Debian system:

$ sudo apt install tox

Then (from the swh-environment/swh-docs/ directory):

$ tox -e sphinx-dev

This tox environment will build the documentation from the sources available in the parent directory (swh-environment).

Behind the scene, this tox environment will run the sphinx documentation building process via pifpaf to encapsulate the need os Postgresql to generate database schemas. The documentation building process itself consists mainly in 3 steps:

1. Generate documentation assets for all modules

$ cd swh-environment
$ make docs-assets

This will not build the documentation in each module (there is make docs for that).

2. Build the api docs for all swh python packages

$ cd swh-docs/docs
$ make apidoc

3. Build the documentation

$ cd swh-docs/docs
$ make

The HTML documentation is now available starting from _build/html/index.html.

Cleaning up

$ cd docs
$ make distclean

The former (make clean) will only clean the local Sphinx build, without touching other modules. The latter (make distclean) will also clean Sphinx builds in all other modules.

Publishing the doc

The publication of the documentation is now managed by the [CI][7].

swh-docs's People

Contributors

abotiamnot avatar anlambert avatar ardumont avatar douardda avatar haltode avatar olasd avatar progval avatar seirl avatar zacchiro avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.