mirror of
https://github.com/uutils/coreutils.git
synced 2026-06-10 15:48:22 -07:00
Add Sphinx documentation to generate man pages
This commit is contained in:
Alex Lyon
@@ -10,3 +10,4 @@ target/
|
||||
.idea
|
||||
Cargo.lock
|
||||
lib*.a
|
||||
/docs/_build
|
||||
Generated
+173
-144
File diff suppressed because it is too large
Load Diff
@@ -22,9 +22,15 @@ PREFIX ?= /usr/local
|
||||
DESTDIR ?=
|
||||
BINDIR ?= /bin
|
||||
LIBDIR ?= /lib
|
||||
MANDIR ?= /man/man1
|
||||
|
||||
INSTALLDIR_BIN=$(DESTDIR)$(PREFIX)$(BINDIR)
|
||||
INSTALLDIR_LIB=$(DESTDIR)$(PREFIX)$(LIBDIR)
|
||||
INSTALLDIR_MAN=$(DESTDIR)$(PREFIX)/share/$(MANDIR)
|
||||
$(shell test -d $(INSTALLDIR_MAN))
|
||||
ifneq ($(.SHELLSTATUS),0)
|
||||
override INSTALLDIR_MAN=$(DESTDIR)$(PREFIX)$(MANDIR)
|
||||
endif
|
||||
|
||||
#prefix to apply to uutils binary and all tool binaries
|
||||
PROG_PREFIX ?=
|
||||
@@ -34,6 +40,7 @@ PROG_PREFIX ?=
|
||||
BASEDIR ?= $(shell pwd)
|
||||
BUILDDIR := $(BASEDIR)/target/${PROFILE}
|
||||
PKG_BUILDDIR := $(BUILDDIR)/deps
|
||||
DOCSDIR := $(BASEDIR)/docs
|
||||
|
||||
BUSYBOX_ROOT := $(BASEDIR)/tmp
|
||||
BUSYBOX_VER := 1.24.1
|
||||
@@ -215,11 +222,6 @@ TEST_NO_FAIL_FAST :=--no-fail-fast
|
||||
TEST_SPEC_FEATURE := test_unimplemented
|
||||
endif
|
||||
|
||||
define BUILD_EXE
|
||||
build_exe_$(1):
|
||||
${CARGO} build ${CARGOFLAGS} ${PROFILE_CMD} -p $(1)
|
||||
endef
|
||||
|
||||
define TEST_BUSYBOX
|
||||
test_busybox_$(1):
|
||||
(cd $(BUSYBOX_SRC)/testsuite && bindir=$(BUILDDIR) ./runtest $(RUNTEST_ARGS) $(1) )
|
||||
@@ -257,14 +259,18 @@ all: build
|
||||
do_install = $(INSTALL) ${1}
|
||||
use_default := 1
|
||||
|
||||
$(foreach util,$(EXES),$(eval $(call BUILD_EXE,$(util))))
|
||||
|
||||
build-pkgs: $(addprefix build_exe_,$(EXES))
|
||||
build-pkgs:
|
||||
ifneq (${MULTICALL}, y)
|
||||
${CARGO} build ${CARGOFLAGS} ${PROFILE_CMD} $(foreach pkg,$(EXES),-p $(pkg))
|
||||
endif
|
||||
|
||||
build-uutils:
|
||||
${CARGO} build ${CARGOFLAGS} --features "${EXES}" ${PROFILE_CMD} --no-default-features
|
||||
|
||||
build: build-uutils build-pkgs
|
||||
build-manpages:
|
||||
cd $(DOCSDIR) && make man
|
||||
|
||||
build: build-uutils build-pkgs build-manpages
|
||||
|
||||
$(foreach test,$(filter-out $(SKIP_UTILS),$(PROGS)),$(eval $(call TEST_BUSYBOX,$(test))))
|
||||
|
||||
@@ -295,28 +301,35 @@ endif
|
||||
|
||||
clean:
|
||||
$(RM) $(BUILDDIR)
|
||||
cd $(DOCSDIR) && make clean
|
||||
|
||||
distclean: clean
|
||||
$(CARGO) clean $(CARGOFLAGS) && $(CARGO) update $(CARGOFLAGS)
|
||||
|
||||
install: build
|
||||
mkdir -p $(INSTALLDIR_BIN)
|
||||
mkdir -p $(INSTALLDIR_LIB)
|
||||
mkdir -p $(INSTALLDIR_MAN)
|
||||
ifeq (${MULTICALL}, y)
|
||||
$(INSTALL) $(BUILDDIR)/uutils $(INSTALLDIR_BIN)/$(PROG_PREFIX)uutils
|
||||
$(foreach prog, $(filter-out uutils, $(INSTALLEES)), \
|
||||
cd $(INSTALLDIR_BIN) && ln -fs $(PROG_PREFIX)uutils $(PROG_PREFIX)$(prog);)
|
||||
cd $(INSTALLDIR_BIN) && $(foreach prog, $(filter-out uutils, $(INSTALLEES)), \
|
||||
ln -fs $(PROG_PREFIX)uutils $(PROG_PREFIX)$(prog) &&) :
|
||||
cat $(DOCSDIR)/_build/man/uutils.1 | gzip > $(INSTALLDIR_MAN)/$(PROG_PREFIX)uutils.1.gz
|
||||
else
|
||||
$(foreach prog, $(INSTALLEES), \
|
||||
$(INSTALL) $(BUILDDIR)/$(prog) $(INSTALLDIR_BIN)/$(PROG_PREFIX)$(prog);)
|
||||
endif
|
||||
mkdir -p $(INSTALLDIR_LIB)
|
||||
$(foreach lib, $(LIBS), $(INSTALL) $(BUILDDIR)/build/*/out/$(lib) $(INSTALLDIR_LIB)/$(lib);)
|
||||
$(foreach lib, $(LIBS), $(INSTALL) $(BUILDDIR)/build/*/out/$(lib) $(INSTALLDIR_LIB)/$(PROG_PREFIX)$(lib) &&) :
|
||||
$(foreach man, $(filter $(INSTALLEES), $(basename $(notdir $(wildcard $(DOCSDIR)/_build/man/*)))), \
|
||||
cat $(DOCSDIR)/_build/man/$(man).1 | gzip > $(INSTALLDIR_MAN)/$(PROG_PREFIX)$(man).1.gz &&) :
|
||||
|
||||
uninstall:
|
||||
ifeq (${MULTICALL}, y)
|
||||
rm -f $(addprefix $(INSTALLDIR_BIN)/,$(PROG_PREFIX)uutils)
|
||||
endif
|
||||
rm -f $(addprefix $(INSTALLDIR_MAN)/,$(PROG_PREFIX)uutils.1.gz)
|
||||
rm -f $(addprefix $(INSTALLDIR_BIN)/$(PROG_PREFIX),$(PROGS))
|
||||
rm -f $(addprefix $(INSTALLDIR_LIB)/,$(LIBS))
|
||||
rm -f $(addprefix $(INSTALLDIR_MAN)/$(PROG_PREFIX),$(addsuffix .1.gz,$(PROGS)))
|
||||
rm -f $(addprefix $(INSTALLDIR_LIB)/$(PROG_PREFIX),$(LIBS))
|
||||
|
||||
.PHONY: all build test distclean clean busytest install uninstall
|
||||
.PHONY: all build build-uutils build-pkgs build-docs test distclean clean busytest install uninstall
|
||||
|
||||
@@ -0,0 +1,20 @@
|
||||
# Minimal makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line.
|
||||
SPHINXOPTS =
|
||||
SPHINXBUILD = sphinx-build
|
||||
SPHINXPROJ = uutils
|
||||
SOURCEDIR = .
|
||||
BUILDDIR = _build
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
.PHONY: help Makefile
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
@@ -0,0 +1,28 @@
|
||||
.. print machine hardware name
|
||||
|
||||
====
|
||||
arch
|
||||
====
|
||||
|
||||
.. FIXME: this needs to be autogenerated somehow
|
||||
|
||||
--------
|
||||
Synopsis
|
||||
--------
|
||||
|
||||
``arch`` [OPTION]...
|
||||
|
||||
-----------
|
||||
Description
|
||||
-----------
|
||||
|
||||
``arch`` is an alias for ``uname -m``. They both print the machine hardware
|
||||
name.
|
||||
|
||||
An exit code of zero indicates success, whereas anything else means failure.
|
||||
For this program, a non-zero exit code generally means the user provided
|
||||
invalid options.
|
||||
|
||||
-h, --help print a help menu for this program displaying accepted
|
||||
options and arguments
|
||||
-v, --version print the version number of this program
|
||||
+184
@@ -0,0 +1,184 @@
|
||||
#!/usr/bin/env python3
|
||||
# -*- coding: utf-8 -*-
|
||||
#
|
||||
# uutils documentation build configuration file, created by
|
||||
# sphinx-quickstart on Tue Dec 5 23:20:18 2017.
|
||||
#
|
||||
# This file is execfile()d with the current directory set to its
|
||||
# containing dir.
|
||||
#
|
||||
# Note that not all possible configuration values are present in this
|
||||
# autogenerated file.
|
||||
#
|
||||
# All configuration values have a default; values that are commented out
|
||||
# serve to show the default.
|
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
#
|
||||
# import os
|
||||
# import sys
|
||||
# sys.path.insert(0, os.path.abspath('.'))
|
||||
|
||||
import glob
|
||||
import os
|
||||
|
||||
# -- General configuration ------------------------------------------------
|
||||
|
||||
# If your documentation needs a minimal Sphinx version, state it here.
|
||||
#
|
||||
# needs_sphinx = '1.0'
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = ['sphinx.ext.imgmath']
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
|
||||
# The suffix(es) of source filenames.
|
||||
# You can specify multiple suffix as a list of string:
|
||||
#
|
||||
# source_suffix = ['.rst', '.md']
|
||||
source_suffix = '.rst'
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = 'index'
|
||||
|
||||
# General information about the project.
|
||||
project = 'uutils'
|
||||
copyright = '2017, uutils developers'
|
||||
author = 'uutils developers'
|
||||
|
||||
# The version info for the project you're documenting, acts as replacement for
|
||||
# |version| and |release|, also used in various other places throughout the
|
||||
# built documents.
|
||||
#
|
||||
# The short X.Y version.
|
||||
version = '0.0.1'
|
||||
# The full version, including alpha/beta/rc tags.
|
||||
release = '0.0.1'
|
||||
|
||||
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||
# for a list of supported languages.
|
||||
#
|
||||
# This is also used if you do content translation via gettext catalogs.
|
||||
# Usually you set "language" from the command line for these cases.
|
||||
language = None
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
# This patterns also effect to html_static_path and html_extra_path
|
||||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use.
|
||||
pygments_style = 'sphinx'
|
||||
|
||||
# If true, `todo` and `todoList` produce output, else they produce nothing.
|
||||
todo_include_todos = False
|
||||
|
||||
|
||||
# -- Options for HTML output ----------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
#
|
||||
html_theme = 'alabaster'
|
||||
|
||||
# Theme options are theme-specific and customize the look and feel of a theme
|
||||
# further. For a list of options available for each theme, see the
|
||||
# documentation.
|
||||
#
|
||||
# html_theme_options = {}
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
html_static_path = ['_static']
|
||||
|
||||
# Custom sidebar templates, must be a dictionary that maps document names
|
||||
# to template names.
|
||||
#
|
||||
# This is required for the alabaster theme
|
||||
# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
|
||||
html_sidebars = {
|
||||
'**': [
|
||||
'relations.html', # needs 'show_related': True theme option to display
|
||||
'searchbox.html',
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
# -- Options for HTMLHelp output ------------------------------------------
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = 'uutilsdoc'
|
||||
|
||||
|
||||
# -- Options for LaTeX output ---------------------------------------------
|
||||
|
||||
latex_elements = {
|
||||
# The paper size ('letterpaper' or 'a4paper').
|
||||
#
|
||||
# 'papersize': 'letterpaper',
|
||||
|
||||
# The font size ('10pt', '11pt' or '12pt').
|
||||
#
|
||||
# 'pointsize': '10pt',
|
||||
|
||||
# Additional stuff for the LaTeX preamble.
|
||||
#
|
||||
# 'preamble': '',
|
||||
|
||||
# Latex figure (float) alignment
|
||||
#
|
||||
# 'figure_align': 'htbp',
|
||||
}
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title,
|
||||
# author, documentclass [howto, manual, or own class]).
|
||||
latex_documents = [
|
||||
(master_doc, 'uutils.tex', 'uutils Documentation',
|
||||
'uutils developers', 'manual'),
|
||||
]
|
||||
|
||||
|
||||
# -- Options for manual page output ---------------------------------------
|
||||
|
||||
# One entry per manual page. List of tuples
|
||||
# (source start file, name, description, authors, manual section).
|
||||
man_pages = []
|
||||
for name in glob.glob('*.rst'):
|
||||
if name != 'index.rst':
|
||||
desc = ''
|
||||
with open(name) as f:
|
||||
desc = f.readline().strip()
|
||||
if desc.startswith('..'):
|
||||
desc = desc[2:].strip()
|
||||
else:
|
||||
desc = ''
|
||||
man_pages.append((
|
||||
name[:-4], # source file without extension
|
||||
name[:-4].replace('/', '-'), # output file
|
||||
desc,
|
||||
[author],
|
||||
1
|
||||
))
|
||||
|
||||
|
||||
# -- Options for Texinfo output -------------------------------------------
|
||||
|
||||
# Grouping the document tree into Texinfo files. List of tuples
|
||||
# (source start file, target name, title, author,
|
||||
# dir menu entry, description, category)
|
||||
texinfo_documents = [
|
||||
(master_doc, 'uutils', 'uutils Documentation',
|
||||
author, 'uutils', 'A cross-platform reimplementation of GNU coreutils in Rust.',
|
||||
'Miscellaneous'),
|
||||
]
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,21 @@
|
||||
.. uutils documentation master file, created by
|
||||
sphinx-quickstart on Tue Dec 5 23:20:18 2017.
|
||||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
Welcome to uutils's documentation!
|
||||
==================================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Contents:
|
||||
|
||||
arch
|
||||
uutils
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
@@ -0,0 +1,36 @@
|
||||
@ECHO OFF
|
||||
|
||||
pushd %~dp0
|
||||
|
||||
REM Command file for Sphinx documentation
|
||||
|
||||
if "%SPHINXBUILD%" == "" (
|
||||
set SPHINXBUILD=sphinx-build
|
||||
)
|
||||
set SOURCEDIR=.
|
||||
set BUILDDIR=_build
|
||||
set SPHINXPROJ=uutils
|
||||
|
||||
if "%1" == "" goto help
|
||||
|
||||
%SPHINXBUILD% >NUL 2>NUL
|
||||
if errorlevel 9009 (
|
||||
echo.
|
||||
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
|
||||
echo.installed, then set the SPHINXBUILD environment variable to point
|
||||
echo.to the full path of the 'sphinx-build' executable. Alternatively you
|
||||
echo.may add the Sphinx directory to PATH.
|
||||
echo.
|
||||
echo.If you don't have Sphinx installed, grab it from
|
||||
echo.http://sphinx-doc.org/
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
|
||||
goto end
|
||||
|
||||
:help
|
||||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
|
||||
|
||||
:end
|
||||
popd
|
||||
@@ -0,0 +1,24 @@
|
||||
.. run core utilities
|
||||
|
||||
======
|
||||
uutils
|
||||
======
|
||||
|
||||
.. FIXME: this needs to be autogenerated somehow
|
||||
|
||||
--------
|
||||
Synopsis
|
||||
--------
|
||||
|
||||
``uutils`` [OPTION]... [PROGRAM] [OPTION]... [ARGUMENTS]...
|
||||
|
||||
-----------
|
||||
Description
|
||||
-----------
|
||||
|
||||
``uutils`` is a program that contains that other coreutils commands, somewhat
|
||||
similar to Busybox.
|
||||
|
||||
--help, -h print a help menu for PROGRAM displaying accepted options and
|
||||
arguments; if PROGRAM was not given, do the same but for this
|
||||
program
|
||||
@@ -7,10 +7,7 @@ authors = []
|
||||
getopts = "0.2.14"
|
||||
time = { version = "0.1.38", optional = true }
|
||||
data-encoding = { version = "^1.1", optional = true }
|
||||
|
||||
[dependencies.libc]
|
||||
git = "https://github.com/rust-lang/libc.git"
|
||||
optional = true
|
||||
libc = { version = "0.2.34", optional = true }
|
||||
|
||||
[features]
|
||||
fs = ["libc"]
|
||||
|
||||
@@ -79,7 +79,7 @@ fn main() {
|
||||
std::process::exit(uumain(args.clone()));
|
||||
}
|
||||
None => {
|
||||
if &args[0][..] == "--help" {
|
||||
if &args[0][..] == "--help" || &args[0][..] == "-h" {
|
||||
// see if they want help on a specific util
|
||||
if args.len() >= 2 {
|
||||
let util = &args[1][..];
|
||||
|
||||
Reference in New Issue
Block a user