# Sphinx Domain for Modern CMake
This is taken directly from the Kitware git repository's Utilities directory.
The original [sphinxcontrib-cmakedomain][] has not been touched in quite some and
as a result it was wildly out of date. Documenting CMake domain entities in
projects is painful otherwise. This works *exactly* in the same way as Kitware,
so some time might be needed to study their approach to these problems.
This repository is under the same License as all of CMake, which is the
BSD-3-Clause license.
🚨🚨🚨
Any issues you run into with this plugin must be reported to [Kitware][],
unless they involve the packaging itself. The Python files exactly match
the CMake source for the released version numbers.
🚨🚨🚨
# Installation
## PyPI
This domain is available via PyPI. Install it directly via `pip`:
```
$ pip install sphinxcontrib-moderncmakedomain
```
Alternatively, place it inside of your `setup.py`, `pyproject.toml`,
`requirements.txt` or whatever system it is that you use to declare and manage
your dependencies. A new version will usually only be released if there is a
change to this extension inside CMake.
## Git
This module is installable via `pip` and GitHub directly as well
```
$ pip install git+https://github.com/scikit-build/moderncmakedomain.git
```
# Usage
To enable the use of the `moderncmakedomain`, add
`sphinxcontrib.moderncmakedomain` to the `extensions` variable of your
`conf.py` file:
```python
extensions = [..., 'sphinxcontrib.moderncmakedomain', ...]
```
The plugin currently provides several directives and references. These are
documented below.
## Directives
| directive | description |
|:------------------:|:----------------------------------------------------|
| `cmake:variable::` | For a basic variable |
| `cmake:command::` | For a function |
| `cmake-module::` | Autodoc style extractor (takes a relative filepath) |
| `cmake:envvar::` | For environment variables |
To declare any of the references found below, they must be placed into a
directory with the same name under the sphinx SOURCEDIR/master doc. Thus,
`prop_tgt/MY_PERSONAL_PROPERTY.rst` can be referred to with
``:prop_tgt:`MY_PERSONAL_PROPERTY` ``. This is currently the *only* way CMake
permits declaring new properties.
## References
Each reference below can be placed into a directory with the same name to
document custom extensions provided by your CMake libraries.
| ref | description |
|:--------------:|:---------------------------------------------------|
| `:variable:` | Refer to a CMake variable |
| `:command:` | Refer to a CMake command |
| `:envvar:` | Refers to an environment variable |
| `:cpack_gen:` | Refers to CPack generators |
| `:generator:` | Refers to a build file generator |
| `:genex:` | Refers to a generator expression |
| `:guide:` | Used to refer to a "guide" page |
| `:manual:` | Used to refer to a "manual" page (like `cmake(1)`) |
| `:policy:` | Refers to CMake Policies |
| `:module:` | Refers to CMake Modules |
| `:prop_tgt:` | For target properties |
| `:prop_test:` | For test properties |
| `:prop_sf:` | For source file properties |
| `:prop_gbl:` | For global properties |
| `:prop_dir:` | For directory properties |
| `:prop_inst:` | For installed file properties |
| `:prop_cache:` | For cache properties |
# History
`sphinx-moderncmakedomain` was initially developed in October 2018 by
[slurps-mad-rips][slurps-mad-rips] to help write CMake documentation by simply
publishing a python package of the same. This was a critical step to ease the
maintenance of sphinx-based documentation and avoid systematically copying the
associated python module maintained within the CMake repository.
Later in early August 2021, [henryiii][henryiii] discovered the
`sphinx-moderncmakedomain` project while working on scikit-build issue
[#574][skbuild-issue-574] intended to simplify its documentation generation
infrastructure and avoid updating its own copy of the sphinx extension.
[henryiii][henryiii] and [jcfr][jcfr] then worked with
[slurps-mad-rips][slurps-mad-rips] to establish a transition plan to
collaboratively maintain the project within the scikit-build organization.
[sphinxcontrib-cmakedomain]: https://github.com/sphinx-contrib/cmakedomain
[Kitware]: https://gitlab.kitware.com/
[skbuild-issue-574]: https://github.com/scikit-build/scikit-build/pull/574
[slurps-mad-rips]: https://github.com/slurps-mad-rips
[henryiii]: https://github.com/henryiii
[jcfr]: https://github.com/jcfr
Raw data
{
"_id": null,
"home_page": "",
"name": "sphinxcontrib-moderncmakedomain",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "cmake,documentation,kitware,sphinx,sphinxcontrib",
"author": "Kitware",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/f7/3a/336fab1fe68263cbc4d9c832e3bf5e410315167091ca124fc6a889d1f96a/sphinxcontrib_moderncmakedomain-3.27.0.tar.gz",
"platform": null,
"description": "# Sphinx Domain for Modern CMake\n\nThis is taken directly from the Kitware git repository's Utilities directory.\nThe original [sphinxcontrib-cmakedomain][] has not been touched in quite some and\nas a result it was wildly out of date. Documenting CMake domain entities in\nprojects is painful otherwise. This works *exactly* in the same way as Kitware,\nso some time might be needed to study their approach to these problems.\n\nThis repository is under the same License as all of CMake, which is the\nBSD-3-Clause license.\n\n\ud83d\udea8\ud83d\udea8\ud83d\udea8\nAny issues you run into with this plugin must be reported to [Kitware][],\nunless they involve the packaging itself. The Python files exactly match\nthe CMake source for the released version numbers.\n\ud83d\udea8\ud83d\udea8\ud83d\udea8\n\n# Installation\n\n## PyPI\n\nThis domain is available via PyPI. Install it directly via `pip`:\n\n```\n$ pip install sphinxcontrib-moderncmakedomain\n```\n\nAlternatively, place it inside of your `setup.py`, `pyproject.toml`,\n`requirements.txt` or whatever system it is that you use to declare and manage\nyour dependencies. A new version will usually only be released if there is a\nchange to this extension inside CMake.\n\n## Git\n\nThis module is installable via `pip` and GitHub directly as well\n\n```\n$ pip install git+https://github.com/scikit-build/moderncmakedomain.git\n```\n\n# Usage\n\nTo enable the use of the `moderncmakedomain`, add\n`sphinxcontrib.moderncmakedomain` to the `extensions` variable of your\n`conf.py` file:\n\n```python\nextensions = [..., 'sphinxcontrib.moderncmakedomain', ...]\n```\n\nThe plugin currently provides several directives and references. These are\ndocumented below.\n\n## Directives\n\n| directive | description |\n|:------------------:|:----------------------------------------------------|\n| `cmake:variable::` | For a basic variable |\n| `cmake:command::` | For a function |\n| `cmake-module::` | Autodoc style extractor (takes a relative filepath) |\n| `cmake:envvar::` | For environment variables |\n\nTo declare any of the references found below, they must be placed into a\ndirectory with the same name under the sphinx SOURCEDIR/master doc. Thus,\n`prop_tgt/MY_PERSONAL_PROPERTY.rst` can be referred to with\n``:prop_tgt:`MY_PERSONAL_PROPERTY` ``. This is currently the *only* way CMake\npermits declaring new properties.\n\n## References\n\nEach reference below can be placed into a directory with the same name to\ndocument custom extensions provided by your CMake libraries.\n\n| ref | description |\n|:--------------:|:---------------------------------------------------|\n| `:variable:` | Refer to a CMake variable |\n| `:command:` | Refer to a CMake command |\n| `:envvar:` | Refers to an environment variable |\n| `:cpack_gen:` | Refers to CPack generators |\n| `:generator:` | Refers to a build file generator |\n| `:genex:` | Refers to a generator expression |\n| `:guide:` | Used to refer to a \"guide\" page |\n| `:manual:` | Used to refer to a \"manual\" page (like `cmake(1)`) |\n| `:policy:` | Refers to CMake Policies |\n| `:module:` | Refers to CMake Modules |\n| `:prop_tgt:` | For target properties |\n| `:prop_test:` | For test properties |\n| `:prop_sf:` | For source file properties |\n| `:prop_gbl:` | For global properties |\n| `:prop_dir:` | For directory properties |\n| `:prop_inst:` | For installed file properties |\n| `:prop_cache:` | For cache properties |\n\n# History\n\n`sphinx-moderncmakedomain` was initially developed in October 2018 by\n[slurps-mad-rips][slurps-mad-rips] to help write CMake documentation by simply\npublishing a python package of the same. This was a critical step to ease the\nmaintenance of sphinx-based documentation and avoid systematically copying the\nassociated python module maintained within the CMake repository.\n\nLater in early August 2021, [henryiii][henryiii] discovered the\n`sphinx-moderncmakedomain` project while working on scikit-build issue\n[#574][skbuild-issue-574] intended to simplify its documentation generation\ninfrastructure and avoid updating its own copy of the sphinx extension.\n[henryiii][henryiii] and [jcfr][jcfr] then worked with\n[slurps-mad-rips][slurps-mad-rips] to establish a transition plan to\ncollaboratively maintain the project within the scikit-build organization.\n\n[sphinxcontrib-cmakedomain]: https://github.com/sphinx-contrib/cmakedomain\n[Kitware]: https://gitlab.kitware.com/\n\n[skbuild-issue-574]: https://github.com/scikit-build/scikit-build/pull/574\n[slurps-mad-rips]: https://github.com/slurps-mad-rips\n[henryiii]: https://github.com/henryiii\n[jcfr]: https://github.com/jcfr\n",
"bugtrack_url": null,
"license": "",
"summary": "Sphinx Domain for Modern CMake",
"version": "3.27.0",
"project_urls": {
"Homepage": "https://github.com/scikit-build/moderncmakedomain"
},
"split_keywords": [
"cmake",
"documentation",
"kitware",
"sphinx",
"sphinxcontrib"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "afd767b518158634508c439eba83d7e5db4c3d6e87b7a0c8d2dd37b7a7b0bb98",
"md5": "319415bdfd8bb76b3a119f18c9c6b4e2",
"sha256": "70a73e0e7cff1b117074e968ccb7f72383ed0f572414df0e216cea06914de988"
},
"downloads": -1,
"filename": "sphinxcontrib_moderncmakedomain-3.27.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "319415bdfd8bb76b3a119f18c9c6b4e2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 13094,
"upload_time": "2023-07-19T02:32:28",
"upload_time_iso_8601": "2023-07-19T02:32:28.850650Z",
"url": "https://files.pythonhosted.org/packages/af/d7/67b518158634508c439eba83d7e5db4c3d6e87b7a0c8d2dd37b7a7b0bb98/sphinxcontrib_moderncmakedomain-3.27.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f73a336fab1fe68263cbc4d9c832e3bf5e410315167091ca124fc6a889d1f96a",
"md5": "23a1aa57365d58f147785547a9d4d6ad",
"sha256": "51e259e91f58d17cc0fac9307fd40106aa59d5acaa741887903fc3660361d1a1"
},
"downloads": -1,
"filename": "sphinxcontrib_moderncmakedomain-3.27.0.tar.gz",
"has_sig": false,
"md5_digest": "23a1aa57365d58f147785547a9d4d6ad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 15897,
"upload_time": "2023-07-19T02:32:29",
"upload_time_iso_8601": "2023-07-19T02:32:29.712476Z",
"url": "https://files.pythonhosted.org/packages/f7/3a/336fab1fe68263cbc4d9c832e3bf5e410315167091ca124fc6a889d1f96a/sphinxcontrib_moderncmakedomain-3.27.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-19 02:32:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "scikit-build",
"github_project": "moderncmakedomain",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinxcontrib-moderncmakedomain"
}
JSON
