Skip to content

Commit

Permalink
Added support for Sphinx-based documentation.
Browse files Browse the repository at this point in the history 
Details:
- Added package 'sphinx' to dev-requirements.txt file.
- Added Sphinx related targets to Makefile.
- Changed default 'all' target in Makefile to 'help'.
- Added missing .PHONY statements for virtual targets in Makefile.
- Created docs subdirectory with Sphinx config file and main file.
- Updated and/or rewrote all docstrings in ld package.
- Applied docs comments from PR 57.
- In README.md, removed the preliminary API documentation,
  improved it and referenced the generated API documentation instead.
  • Loading branch information
@andy-maier
andy-maier committed Mar 13, 2016
1 parent 063f066 commit fd74599
Show file tree
Hide file tree
Showing 8 changed files with 1,237 additions and 420 deletions.
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ __pycache__/
/env/
/bin/
/build/
/build_docs/
/develop-eggs/
/dist/
/eggs/
Expand Down
110 changes: 102 additions & 8 deletions Makefile
View file
Original file line number Diff line number Diff line change
@@ -1,28 +1,122 @@
.PHONY: release install files test docs prepare publish

all:
@echo "make release - prepares a release and publishes it"
@echo "make dev - prepares a development environment (includes tests)"
@echo "make instdev - prepares a development environment (no tests)"
@echo "make install - install on local system"
@echo "make test - run tox"
@echo "make publish - upload to pypi"
# Name of this package
PACKAGENAME = ld

# Additional options for Sphinx
SPHINXOPTS = -v

# Paper format for the Sphinx LaTex/PDF builder.
# Valid values: a4, letter
SPHINXPAPER = a4

# Sphinx build subtree.
SPHINXBUILDDIR = build_docs

# Directory where conf.py is located
SPHINXCONFDIR = docs

# Directory where input files for Sphinx are located
SPHINXSOURCEDIR = .

# Sphinx build command (Use 'pip install sphinx' to get it)
SPHINXBUILD = sphinx-build

# Internal variables for Sphinx
SPHINXPAPEROPT_a4 = -D latex_paper_size=a4
SPHINXPAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(SPHINXBUILDDIR)/doctrees -c $(SPHINXCONFDIR) \
$(SPHINXPAPEROPT_$(SPHINXPAPER)) $(SPHINXOPTS) \
$(SPHINXSOURCEDIR)

.PHONY: help
help:
@echo 'Please use "make <target>" where <target> is one of'
@echo " release - build a release and publish it"
@echo " dev - prepare a development environment (includes tests)"
@echo " instdev - prepare a development environment (no tests)"
@echo " install - install into current Python environment"
@echo " test - test from this directory using tox, including test coverage"
@echo " publish - upload to PyPI"
@echo " html - generate docs as standalone HTML files in: $(SPHINXBUILDDIR)/html"
@echo " pdf - generate docs as PDF (via LaTeX) for paper format: $(SPHINXPAPER) in: $(SPHINXBUILDDIR)/pdf"
@echo " man - generate docs as manual pages in: $(SPHINXBUILDDIR)/man"
@echo " docchanges - generate an overview of all changed/added/deprecated items in docs"
@echo " doclinkcheck - check all external links in docs for integrity"
@echo " doccoverage - run coverage check of the documentation"
@echo " clean - remove any temporary build products"
@echo " clobber - remove any build products"

.PHONY: release
release: publish
@echo "$@ done."

.PHONY: dev
dev: instdev test
@echo "$@ done."

.PHONY: instdev
instdev:
pip install -r dev-requirements.txt
python setup.py develop
@echo "$@ done."

.PHONY: install
install:
python setup.py install
@echo "$@ done."

.PHONY: test
test:
sudo pip install 'tox>=1.7.2'
tox
@echo "$@ done."

.PHONY: publish
publish:
python setup.py sdist upload
@echo "$@ done; uploaded the ld package to PyPI."

.PHONY: html
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/html
@echo "$@ done; the HTML pages are in $(SPHINXBUILDDIR)/html."

.PHONY: pdf
pdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/pdf
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(SPHINXBUILDDIR)/pdf all-pdf
@echo "$@ done; the PDF files are in $(SPHINXBUILDDIR)/pdf."

.PHONY: man
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/man
@echo "$@ done; the manual pages are in $(SPHINXBUILDDIR)/man."

.PHONY: docchanges
docchanges:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/changes
@echo
@echo "$@ done; the doc changes overview file is in $(SPHINXBUILDDIR)/changes."

.PHONY: doclinkcheck
doclinkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/linkcheck
@echo
@echo "$@ done; look for any errors in the above output " \
"or in $(SPHINXBUILDDIR)/linkcheck/output.txt."

.PHONY: doccoverage
doccoverage:
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/coverage
@echo "$@ done; the doc coverage results are in $(SPHINXBUILDDIR)/coverage/python.txt."

.PHONY: clean
clean:
rm -rf build $(PACKAGENAME).egg-info
@echo "$@ done."

.PHONY: clobber
clobber: clean
rm -rf $(SPHINXBUILDDIR)
@echo "$@ done."
212 changes: 37 additions & 175 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,22 +5,30 @@ ld
[![PyPI](http://img.shields.io/pypi/dm/ld.svg)](http://img.shields.io/pypi/dm/ld.svg)
[![PypI](http://img.shields.io/pypi/v/ld.svg)](http://img.shields.io/pypi/v/ld.svg)

Python 3.5 deprecates `platform.linux_distribution()` and Python 3.7 removes it altogether.
The `ld` (linux distribution) package provides information about the
Linux distribution it runs on, such as a reliable machine-readable ID, or
version information.

Still, there are many cases in which you need access to that information.
It is a renewed alternative implementation for Python's
original `platform.linux_distribution` function, but it also provides much more
functionality.
An alternative implementation became necessary because Python 3.5 deprecated
this function, and Python 3.7 is expected to remove it altogether.
Its predecessor function `platform.dist` was already deprecated since
Python 2.6 and is also expected to be removed in Python 3.7.
Still, there are many cases in which access to that information is needed.
See [Python issue 1322](https://bugs.python.org/issue1322) for more
information.

see [https://bugs.python.org/issue1322](https://bugs.python.org/issue1322) for more information.
The `ld` package implements a robust and inclusive way of retrieving the
information about a Linux distribution based on new standards and old methods,
namely from these data sources (from high to low precedence):

THIS IS WIP! It is is no means production ready. See caveats section.
* The os-release file `/etc/os-release`, if present.
* The output of the `lsb_release` command, if available.
* The distro release file (`/etc/*(-|_)(release|version)`), if present.


`ld` (linux distribution) attempts to implement a more robust and inclusive way of retrieving the distro related information based on new standards and old methods - namely:

* `/etc/os-release`
* the output of the `lsb_release -a` command
* `/etc/*-release`

`ld` is tested on Python 2.6, 2.7 and 3.5
`ld` is tested on Python 2.6, 2.7 and 3.5.


## Installation
Expand All @@ -37,186 +45,40 @@ pip install https://github.com/nir0s/ld/archive/master.tar.gz

## Distribution Support

The following distributions are tested (this is by no means an exhaustive list of supported distros as any distro adhering to the same standards should work):
The following distributions are tested (this is by no means an exhaustive list
of supported distros as any distro adhering to the same standards should work):

* Arch
* CentOS 5/7
* Debian 8
* Exherbo
* Fedora 23
* OpenSuSE 42
* Oracle 7
* Red Hat 6/7
* Mageia 5
* openSUSE Leap 42
* Oracle Linux Server 7
* RHEL 6/7
* Slackware 14
* Ubuntu 14


## Usage

```python

import ld

ld.linux_distribution(full_distribution_name=False)

'('centos', '7.1.1503', 'Core')'
```

## Exposed Distribution Properties

`ld` exposes the following parmeters:

### `ld.linux_distribution(full_distribution_name=False)`

Attempts to implement Python's `platform.linux_distribution()`.

If `full_distribution_name` is set to `True`, the `name` will be returned instead of the `id`.

### `ld.id()`

Returns the id of the distribution - e.g. `ubuntu`, `fedora`, `debian`...

The id should be machine-readable.

#### Lookup Hierarchy

* os-release['ID']
* lsb-release['Distributor ID'] in lowercase.
* *-release file name prefix (e.g. redhat from redhat-release)

### `ld.name()`

Returns the name of the distribution - e.g. `Red Hat Enterprise Linux Server`, `Ubuntu`, `openSUSE Leap`

#### Lookup Hierarchy

* os-release['NAME']
* lsb-release['Distributor ID']
* first part of the first line of the *-release file

### `ld.name(pretty=True)`

Returns a prettified name of the distribution - e.g. `openSUSE Leap 42.1 (x86_64)`, `CentOS Linux 7 (Core)`, `Oracle Linux Server 7.1`

#### Lookup Hierarchy

* os-release['PRETTY_NAME']
* lsb-release['Description']
* first part of the first line of the *-release file + `ld.version(pretty=True)`

### `ld.version()`

Returns the version (i.e. release) of the distribution - e.g. .. well.. the version number.

### Lookup Hierarchy

* os-release['VERSION_ID']
* lsb-release['Release']
* second part of the first line of the *-release file

`ld.minor_version()`, `ld.major_version()` and `ld.build_number()` are also exposed and are based on `ld.version_parts()`.

### `ld.version(pretty=True)`

Returns a prettified version of the distribution - e.g. `7 (Core)`, `23 (Twenty Three)`

### Lookup Hierarchy

* os-release['VERSION']
* lsb-release['Release'] + `ld.codename()` (if codename exists)
* second part of the first line of the *-release file + `ld.codename()` (if codename exists)

### `ld.like()`

Returns the os-release['ID_LIKE'] field - e.g. `suse`, `rhel fedora`, `debian`


### `ld.codename()`

Returns the distribution version's codename - e.g. `Core`, `trusty`, `Maipo`

Note that not all distributions provide a codename for their releases.

#### Lookup Hierarchy

* The second part of os-release['VERSION'] (between parentheses or after a comma)
* lsb-release['Codename']
* third part of the first line of the *-release files (between parentheses)

### `ld.base()`

Returns the base distribution - e.g. `arch`, `gentoo`, `rhel`

`constants.py` contains the table in which each distro is mapped to its base distro.

Matching is one first by `ld.name()` and then by `ld.like()`

### `ld.info()`

Returns a dictionary with machine readable info of the distribution.
This is just an aggregate of the rest of the information.

Example:

```python
{
'id': 'rhel',
'version': '7.0',
'version_parts': {
'major': '7',
'minor': '0',
'build_number': ''
},
'like': 'fedora',
'base': 'fedora'
}
python
>>> import ld
>>> ld.linux_distribution(full_distribution_name=False)
'('centos', '7.1.1503', 'Core')'
```

Several more functions are available. For a complete description of the
API, see the [latest API documentation](http://ld.readthedocs.org/en/latest/).

### Retrieving information directly

* `ld.os_release_info()` - returns a dictionary containing the info found in `/etc/os-release`
* `ld.lsb_release_info()` - returns a dictionary containing the info parsed from `lsb_release -a`
* `ld.distro_release_info()` - returns a dictionary containing the info found in '/etc/*-release' matching your distribution.

You can also get the information from some of the release files directly. This allows you to retrieve information that is not exposed via the API.

For instance, RHEL 7's os-release file contains the following:

`REDHAT_BUGZILLA_PRODUCT="Red Hat Enterprise Linux 7"`

`ld.get_os_release_attr('redhat_bugzilla_product')` will get the value for that field.

`ld.get_lsb_release_attr()` and `ld.get_dist_release_attr()` are also exposed.


## Lookup Locations

* [os-release](http://www.freedesktop.org/software/systemd/man/os-release.html) is a new standard for providing distro-specific information. This is the first file looked at when attempting to retrieve the distro specific info.
* [lsb_release](http://linux.die.net/man/1/lsb_release) is found by default in Ubuntu. We also check for `lsb_release -a` to retrieve the information from it if it is available.
* `*-release` - We fallback to the release file specific to the distribution (e.g. `/etc/redhat-release`, `/etc/centos-release`) and try to extract information (like the version and codename) from it. This is done by looking up the a release file and parsing it.

## Caveats

contributors, please read.

* There will be some consistency issues depending on the system you're running. For instance, `os-release` returns `rhel` as an id while `redhat-release` returns `redhat`. This means that either the user will have to act upon "either redhat or rhel" or we'll have to decide on one of them and then convert in-code.
* `codename` of the same distro might be different in some cases. For instance, `os-release` returns `Trusty Tahr` for Ubuntu 14.04 while `lsb_release -a` returns `trusty`. This again means that we'll either have to tell the user to check `codename.lower().startswith(WHATEVER)` or find a consistent way of dealing with codenames. All in all, relying on version numbers is preferred.

## Testing

```shell
git clone git@github.com:nir0s/ld.git
cd ld
pip install tox
tox
```

## Contributions..
## Contributions

Pull requests are always welcome to deal with specific distributions or just for general merriment.
Pull requests are always welcome to deal with specific distributions or just
for general merriment.

Reference implementations for supporting additional distributions and file formats can be found here:
Reference implementations for supporting additional distributions and file
formats can be found here:

* https://github.com/saltstack/salt/blob/develop/salt/grains/core.py#L1172
* https://github.com/chef/ohai/blob/master/lib/ohai/plugins/linux/platform.rb
3 changes: 2 additions & 1 deletion dev-requirements.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,5 @@ coverage==3.7.1
nose
nose-cov
testfixtures
testtools
testtools
sphinx>=1.1
Loading

0 comments on commit fd74599

Please sign in to comment.