**Archived**
This project is legacy and should not be used for new documentation. Existing documentation projects using it should be migrated to `the Discourse model <https://canonical-webteam.github.io/practices/project-structure/documentation.html#community-documentation>`_, or use another solution. If you manage such a project, please reach out to us to facilitate the upgrade.
----
Ubuntu documentation builder
============================
Maintenance mode
----------------
`documentation-builder` is now considered a legacy product, as all user maintained documentation sets should now be moving to the `discourse-docs model <https://canonical-webteam.github.io/practices/project-structure/documentation.html#community-documentation>`__.
Important fixes will still be performed, but we will not be adding new features.
----
.. image:: https://travis-ci.org/CanonicalLtd/documentation-builder.svg?branch=master
:alt: build status
:target: https://travis-ci.org/CanonicalLtd/documentation-builder
.. image:: https://coveralls.io/repos/github/CanonicalLtd/documentation-builder/badge.svg?branch=master
:alt: code coverage
:target: https://coveralls.io/github/CanonicalLtd/documentation-builder
A tool for building a set of documentation files in HTML format, from a
remote git repository containing markdown files.
Installation
------------
The best way to install `documentation-builder` is with `snap <https://snapcraft.io>`__:
.. code:: bash
sudo snap install documentation-builder
If you don't have `snap` on your system, you can also install it with `pip3`:
.. code:: bash
pip3 install ubuntudesign.documentation-builder
For more information see `the documentation <docs/en/>`__.
Development
-----------
documentation-builder is a Python module. The main application code lives in
`ubuntudesign/documentation_builder <ubuntudesign/documentation_builder>`__. Updates
to the markup or styling should be made in `the default template <ubuntudesign/documentation_builder/resources/template.html>`__.
Checking changes
~~~~~~~~~~~~~~~~
To check your changes to documentation-builder, it's probably easiest to install the module locally, in editable mode, within an encapsulated environment:
.. code:: bash
python3 -m venv env3 && source env3/bin/activate # Create encapsulated environment
pip install -e . # Install the module in editable mode
documentation-builder --source-folder docs # build the documentation-builder's own documentation
xdg-open build/en/index.html # Open up the documentation page
Watching for changes
~~~~~~~~~~~~~~~~~~~~
On Ubuntu et al. you can use `inotifywait` to watch for changes to the source files, and rebuild when something changes as follows:
.. code:: bash
sudo apt install inotify-tools # Ensure inotifywait is installed
# Force rebuild docs when anything changes in the source folder
while inotifywait -r -e close_write "./ubuntudesign"; do bin/documentation-builder --force --source-folder docs; done
Tests
~~~~~
To run tests:
.. code:: bash
./setup.py test
Debugging
*********
To run a specific test:
.. code:: bash
./setup.py test --addopts tests/test_operations.py::test_find_files
You can debug tests by `adding a debugger to the code <https://www.safaribooksonline.com/blog/2014/11/18/intro-python-debugger/>`__ and running the test again.
Raw data
{
"_id": null,
"home_page": "https://github.com/ubuntudesign/documentation-builder",
"name": "ubuntudesign.documentation-builder",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Canonical webteam",
"author_email": "robin+pypi@canonical.com",
"download_url": "https://files.pythonhosted.org/packages/7d/3a/72ebe6876f0e556eba5de8696d651d6828062f6e565954018af751fdfcd1/ubuntudesign.documentation-builder-1.7.0.tar.gz",
"platform": null,
"description": " **Archived**\n \n This project is legacy and should not be used for new documentation. Existing documentation projects using it should be migrated to `the Discourse model <https://canonical-webteam.github.io/practices/project-structure/documentation.html#community-documentation>`_, or use another solution. If you manage such a project, please reach out to us to facilitate the upgrade.\n \n----\n\nUbuntu documentation builder\n============================\n\nMaintenance mode\n----------------\n\n`documentation-builder` is now considered a legacy product, as all user maintained documentation sets should now be moving to the `discourse-docs model <https://canonical-webteam.github.io/practices/project-structure/documentation.html#community-documentation>`__.\n\nImportant fixes will still be performed, but we will not be adding new features.\n\n----\n\n.. image:: https://travis-ci.org/CanonicalLtd/documentation-builder.svg?branch=master\n :alt: build status\n :target: https://travis-ci.org/CanonicalLtd/documentation-builder\n\n.. image:: https://coveralls.io/repos/github/CanonicalLtd/documentation-builder/badge.svg?branch=master\n :alt: code coverage\n :target: https://coveralls.io/github/CanonicalLtd/documentation-builder\n\nA tool for building a set of documentation files in HTML format, from a\nremote git repository containing markdown files.\n\nInstallation\n------------\n\nThe best way to install `documentation-builder` is with `snap <https://snapcraft.io>`__:\n\n.. code:: bash\n\n sudo snap install documentation-builder\n\nIf you don't have `snap` on your system, you can also install it with `pip3`:\n\n.. code:: bash\n\n pip3 install ubuntudesign.documentation-builder\n\nFor more information see `the documentation <docs/en/>`__.\n\nDevelopment\n-----------\n\ndocumentation-builder is a Python module. The main application code lives in\n`ubuntudesign/documentation_builder <ubuntudesign/documentation_builder>`__. Updates\nto the markup or styling should be made in `the default template <ubuntudesign/documentation_builder/resources/template.html>`__.\n\nChecking changes\n~~~~~~~~~~~~~~~~\n\nTo check your changes to documentation-builder, it's probably easiest to install the module locally, in editable mode, within an encapsulated environment:\n\n.. code:: bash\n\n python3 -m venv env3 && source env3/bin/activate # Create encapsulated environment\n pip install -e . # Install the module in editable mode\n\n documentation-builder --source-folder docs # build the documentation-builder's own documentation\n xdg-open build/en/index.html # Open up the documentation page\n\nWatching for changes\n~~~~~~~~~~~~~~~~~~~~\n\nOn Ubuntu et al. you can use `inotifywait` to watch for changes to the source files, and rebuild when something changes as follows:\n\n.. code:: bash\n\n sudo apt install inotify-tools # Ensure inotifywait is installed\n\n # Force rebuild docs when anything changes in the source folder\n while inotifywait -r -e close_write \"./ubuntudesign\"; do bin/documentation-builder --force --source-folder docs; done\n\nTests\n~~~~~\n\nTo run tests:\n\n.. code:: bash\n\n ./setup.py test\n\nDebugging\n*********\n\nTo run a specific test:\n\n.. code:: bash\n\n ./setup.py test --addopts tests/test_operations.py::test_find_files\n\nYou can debug tests by `adding a debugger to the code <https://www.safaribooksonline.com/blog/2014/11/18/intro-python-debugger/>`__ and running the test again.\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "A command-line tool for building documentation from repositories into HTML files. Initially based on https://github.com/juju/docs/blob/master/tools/mdbuild.py.",
"version": "1.7.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7d3a72ebe6876f0e556eba5de8696d651d6828062f6e565954018af751fdfcd1",
"md5": "b4e9303179b074a40beae80eebcd8035",
"sha256": "d517ecf531cf91ac8e0a39f20ccc07747e18136914c5f0df3465ad1f3a386300"
},
"downloads": -1,
"filename": "ubuntudesign.documentation-builder-1.7.0.tar.gz",
"has_sig": false,
"md5_digest": "b4e9303179b074a40beae80eebcd8035",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 50819,
"upload_time": "2023-01-30T13:54:21",
"upload_time_iso_8601": "2023-01-30T13:54:21.055627Z",
"url": "https://files.pythonhosted.org/packages/7d/3a/72ebe6876f0e556eba5de8696d651d6828062f6e565954018af751fdfcd1/ubuntudesign.documentation-builder-1.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-30 13:54:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "ubuntudesign",
"github_project": "documentation-builder",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"lcname": "ubuntudesign.documentation-builder"
}
JSON
