Skip to content

daschuer/manual

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Mixxx User Manual

This repository contains the sources for the Mixxx User Manual as found at http://mixxx.org/manual/latest/.

The manual is written in reStructuredText format using the Sphinx documentation generator.

Steps for use:

  • Install Sphinx, the documentation generator
  • Install Graphviz, a graph visualization software (is used to draw some diagrams)
  • Download the latest Mixxx manual source or clone the repository git clone https://github.com/mixxxdj/manual.git
  • Edit .rst files in source/
  • Run make html to build an HTML version of the manual
  • Open the file build/html/index.html in your Web browser to view the results

Run make linkcheck in the terminal. Sphinx will validate all internal and external links in the document, and let you know if any links are malformed, or point to dead URLs.

Guidelines for Mixxx Manual writers

The Mixxx manual is based on sound learning principles, and is supposed to be user-friendly & motivational. Please refer to the guidelines for style conventions.

  • Open the files source/manual_guidelines.rst in your editor or build/html/manual_guidelines.html in your Web browser.

Editing the manual using git (recommended)

  • Clone the repository git clone https://github.com/mixxxdj/manual.git
  • Perform changes
  • Commit changes git commit -m "Insert short summary of your changes here"
  • Push changes git push
  • Submit a pull request

Editing the manual on Github


Sphinx and RST syntax guides:

Editors with Restructured Text (reST) syntax highlighting

Still not enough?

Even more reStructuredText resources: http://stackoverflow.com/questions/2746692/restructuredtext-tool-support


Release Checklist for maintainers

  • Fix and delete todos listed in build/html/todolist.html
  • Fix and close issues listed in https://github.com/mixxxdj/manual/issues
  • Temporarily disable the For documentation writers toctree from TOC in /index.rst
  • Update the release and version tags in /conf.py
  • Tag the repository with the version number, and create a new release.
  • Run make html to produce html output ready for upload to http://mixxx.org/manual/latest/
  • Check the output compiles correctly and does not produce any warnings
  • Run make latexpdf to produce pdf output for distribution
  • Run make latexpdf again, or the TOC is missing from the resulting pdf

About

The Mixxx Manual

Resources

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Python 45.6%
  • Makefile 28.0%
  • Shell 26.4%