معرفی شرکت ها
doctr-versions-menu-0.4.1
تبلیغات ما
مشتریان به طور فزاینده ای آنلاین هستند. تبلیغات می تواند به آنها کمک کند تا کسب و کار شما را پیدا کنند.
مشاهده بیشتر
تبلیغات ما
مشتریان به طور فزاینده ای آنلاین هستند. تبلیغات می تواند به آنها کمک کند تا کسب و کار شما را پیدا کنند.
مشاهده بیشتر
تبلیغات ما
مشتریان به طور فزاینده ای آنلاین هستند. تبلیغات می تواند به آنها کمک کند تا کسب و کار شما را پیدا کنند.
مشاهده بیشتر
تبلیغات ما
مشتریان به طور فزاینده ای آنلاین هستند. تبلیغات می تواند به آنها کمک کند تا کسب و کار شما را پیدا کنند.
مشاهده بیشتر
تبلیغات ما
مشتریان به طور فزاینده ای آنلاین هستند. تبلیغات می تواند به آنها کمک کند تا کسب و کار شما را پیدا کنند.
مشاهده بیشترتوضیحات
Sphinx extension and command to add a versions menu to Doctr-deployed documentation
| ویژگی | مقدار |
|---|---|
| سیستم عامل | - |
| نام فایل | doctr-versions-menu-0.4.1 |
| نام | doctr-versions-menu |
| نسخه کتابخانه | 0.4.1 |
| نگهدارنده | [] |
| ایمیل نگهدارنده | [] |
| نویسنده | Michael Goerz |
| ایمیل نویسنده | mail@michaelgoerz.net |
| آدرس صفحه اصلی | https://github.com/goerz/doctr_versions_menu |
| آدرس اینترنتی | https://pypi.org/project/doctr-versions-menu/ |
| مجوز | MIT license |
===================
Doctr Versions Menu
===================
.. image:: https://img.shields.io/badge/goerz-doctr__versions__menu-blue.svg?logo=github
:alt: Source code on Github
:target: https://github.com/goerz/doctr_versions_menu
.. image:: https://img.shields.io/badge/docs-doctr-blue.svg
:alt: Documentation
:target: https://goerz.github.io/doctr_versions_menu/
.. image:: https://img.shields.io/pypi/v/doctr_versions_menu.svg
:alt: doctr-versions-menu on the Python Package Index
:target: https://pypi.python.org/pypi/doctr_versions_menu
.. image:: https://img.shields.io/travis/goerz/doctr_versions_menu.svg
:alt: Travis Docs CD
:target: https://travis-ci.com/goerz/doctr_versions_menu
.. image:: https://github.com/goerz/doctr_versions_menu/workflows/Tests/badge.svg?branch=master
:alt: Tests
:target: https://github.com/goerz/doctr_versions_menu/actions?query=workflow%3ATests
.. image:: https://img.shields.io/coveralls/github/goerz/doctr_versions_menu/master.svg
:alt: Coveralls
:target: https://coveralls.io/github/goerz/doctr_versions_menu?branch=master
.. image:: https://img.shields.io/badge/License-MIT-green.svg
:alt: MIT License
:target: https://opensource.org/licenses/MIT
Sphinx_ extension and command to add a versions menu to Doctr_-deployed documentation.
Doctr_ is a tool that deploys Sphinx_ documentation from `Travis CI <Travis_>`_
to `Github Pages`_. It is an alternative to the popular `Read the Docs`_ (RTD).
Compared to RTD, Doctr gives full control over the documentation build process.
However, Doctr out of the box does not support documentation for multiple
versions of a package at the same time (unlike RTD).
The ``doctr-versions-menu`` package aims to remedy this. It provides a Sphinx
extension and a command line tool that work together to generate a dynamic
versions menu similar to that on RTD pages:
.. image:: https://raw.githubusercontent.com/goerz/doctr_versions_menu/master/docs/_static/doctr-versions-menu-screenshot.png
:alt: Doctr Versions Menu Screenshot
It also injects warnings for outdated or unreleased versions.
See the ``doctr-versions-menu`` documentation itself for a `live example <online_>`_.
Development of Doctr Versions Menu happens on `Github`_.
You can read the full documentation online_.
⚠️ **As of December 2020, Travis no longer provides free services to open source projects.** See `Deployment with Github Actions <https://goerz.github.io/doctr_versions_menu/v0.4.0/command.html#deployment-with-github-actions>`_ for a workaround.
Installation
------------
To install the latest released version of ``doctr-versions-menu``, run:
.. code-block:: shell
pip install doctr-versions-menu
Or, to install the latest development version of ``doctr-versions-menu`` from `Github`_:
.. code-block:: shell
pip install git+https://github.com/goerz/doctr_versions_menu.git@master#egg=doctr_versions_menu
The ``doctr-versions-menu`` package can also be installed through conda_, using
the conda-forge_ channel. See the `instructions in the Doctr Versions Menu
Feedstock <conda-feedstock-instructions_>`_.
In practice, you probably only have to install the ``doctr-versions-menu``
package on Travis_, for generating and deploying the documentation; or, e.g.,
in a local tox_ environment for generating documentation locally during
development.
Usage
-----
Showing a versions menu in your documentation requires two steps:
1. Add ``'doctr_versions_menu'`` to the list of extensions in your Sphinx ``conf.py``.
This adds javascript to your rendered documentation that displays a dynamic versions menu based on information in a ``versions.json`` file it expects to find in the root for your ``gh-pages`` branch.
2. Call the ``doctr-versions-menu`` command as part of ``doctr deploy`` (in ``.travis.yml``).
For example,
.. code-block:: shell
doctr deploy --command=doctr-versions-menu --no-require-master --build-tags "$DEPLOY_DIR"
This causes ``doctr-versions-menu`` to be executed in the root of the ``gh-pages`` branch. The script examines the folders that exist there, and generates the ``versions.json`` file that step 1 relies on.
See the `full documentation <online_>`_ on Step 1 and Step 2 for details. However, for projects that follow normal best practices, **you should not require any customization beyond the above two steps**.
Examples
--------
The following projects use ``doctr-versions-menu``:
* Krotov_
* caproto_
* pcds-ci-helpers_ (an example of shared Travis CI configurations using doctr-versions-menu)
* lcls-twincat-general_ (among many other PLC projects at the LCLS)
.. _Github: https://github.com/goerz/doctr_versions_menu
.. _Github pages: https://pages.github.com
.. _Doctr: https://drdoctr.github.io
.. _Sphinx: https://www.sphinx-doc.org/
.. _online: https://goerz.github.io/doctr_versions_menu/
.. _Read the Docs: https://readthedocs.org
.. _Travis: https://travis-ci.org
.. _tox: https://tox.readthedocs.io
.. _Krotov: https://qucontrol.github.io/krotov/
.. _caproto: https://caproto.github.io/caproto/
.. _pcds-ci-helpers: https://github.com/pcdshub/pcds-ci-helpers/blob/d1bb15ace06cfd8fdda3f5ccad0981fcc59dfbe0/travis/shared_configs/doctr-upload.yml
.. _lcls-twincat-general: https://pcdshub.github.io/lcls-twincat-general/
.. _conda: https://docs.conda.io
.. _conda-forge: https://conda-forge.org
.. _conda-feedstock-instructions: https://github.com/conda-forge/doctr-versions-menu-feedstock#installing-doctr-versions-menu
=======
History
=======
0.4.1 (2021-03-18)
------------------
* Fixed: The ``doctr-versions-menu`` exectuable no longer fails when run outside of a git repository (`#15`_, thanks to `Alexander Blech <@ablech_>`_)
* Fixed: Custom ``doctr-versions-menu.js_t`` template were being ignored (`#18`_)
0.4.0 (2020-12-14)
------------------
* Added: The label in the top left corner of the version menu can now be configured in ``conf.py`` (setting ``menu_title``).
* Added: ``--default-branch`` option, ``<default-branch>`` group for folder specifications, and ``default-branch`` field in ``versions.json`` (`#12`_)
* Changed: The default ``--versions`` now uses ``<default-branch>``, automatically picking up on either "master" or "main" as the default branch (`#12`_)
* Changed: The default template for ``index.html`` now automatically forwards to the default-branch (based on the ``--default-branch`` option, instead of just "master"), or the first available branch if there is no released version (`#12`_)
This release addresses two major compatibility issues:
1. Both `git <GitMainDefaultBranch_>`_ and `Github <GithubMainDefaultBranch_>`_ have recently switched the name of the default branch from "master" to "main". This release adds support for new projects using "main" as their default branch.
2. As of December 2020, Travis CI has `stopped their support for open source <TravisDemiseHN_>`_. Consequently, Doctr_ can no longer be used to deploy documentation at no cost. This release adds rudimentary support for deploying the documenation with `Github Actions`_ instead of Doctr, see `Deployment with Github Actions <https://goerz.github.io/doctr_versions_menu/v0.4.0/command.html#deployment-with-github-actions>`_.
0.3.0 (2020-08-03)
------------------
* Added: ``--no-downloads-file`` option, ``downloads_file = False`` in config. (`#4`_, thanks to `Tyler Pennebaker <@ZryletTC_>`_)
* Fixed: ``versions.py`` on ``gh-pages`` branch was not being committed (`#5`_)
* Fixed: Compatibility with any ``pyparsing`` version ``>= 2.0.2`` (`#8`_, thanks to `Hugo Slepicka <@hhslepicka_>`_)
* Added: The ``doctr-versions-menu`` executable can now be configured through environment variables. This allows to keep configuration on the source branch, in the ``.travis.yml`` file (`#6`_, thanks to `Tyler Pennebaker <@ZryletTC_>`_)
* The Doctr Versions Menu package can now be installed via `conda <conda-feedstock_>`_ (thanks to `Hugo Slepicka <@hhslepicka_>`_)
0.2.0 (2020-03-14)
------------------
* Added: ``--versions`` option for customizing which folders appear in the versions menu and in which order.
* Added: ``--label`` option for customizing the labels appearing the versions menu
* Added: ``--warning`` option for customizing on which folders specific warnings are displayed
* Added: ``--latest`` option for configuring which folder is the "latest stable release"
* Added: Write a script ``versions.py`` to the root of the ``gh-pages`` branch (``--write-versions-py`` option)
* Changed: unreleased and pre-released versions now show different warnings by default
* Changed: ``index.html`` template is now rendered with full ``version_data``
* Changed: development/pre-release versions now longer have the "dev" suffix in the versions menu by default
* Changed: The versions menu now uses the same ordering of versions as Read-the-Docs, by default: the folders are ordered from most current to least current.
* Changed: internal format of ``versions.json``
* Removed: ``--default-branch`` option. This is replaced by the new ``--latest`` option and enhanced template rendering of the ``index.html``
* Removed: ``--suffix-unreleased`` option. This can now be achieved via the ``--label`` option
This is a major release that breaks backwards compatibility.
Specifically, due to the changes in ``versions.json``, when upgrading from older versions, it
may be necessary to replace ``doctr-versions-menu.js`` files in existing
folders in a project's ``gh-pages`` branch.
0.1.0 (2020-01-11)
------------------
* Initial release
.. _GithubMainDefaultBranch: https://github.blog/changelog/2020-10-01-the-default-branch-for-newly-created-repositories-is-now-main/
.. _GitMainDefaultBranch: https://github.blog/2020-07-27-highlights-from-git-2-28/#introducing-init-defaultbranch
.. _TravisDemiseHN: https://news.ycombinator.com/item?id=25338983
.. _Doctr: https://drdoctr.github.io
.. _Github Actions: https://github.com/features/actions
.. _@ZryletTC: https://github.com/ZryletTC
.. _@hhslepicka: https://github.com/hhslepicka
.. _@ablech: https://github.com/ablech/
.. _#4: https://github.com/goerz/doctr_versions_menu/issues/4
.. _#5: https://github.com/goerz/doctr_versions_menu/issues/5
.. _#6: https://github.com/goerz/doctr_versions_menu/issues/6
.. _#8: https://github.com/goerz/doctr_versions_menu/issues/8
.. _#12: https://github.com/goerz/doctr_versions_menu/issues/12
.. _#15: https://github.com/goerz/doctr_versions_menu/issues/15
.. _#18: https://github.com/goerz/doctr_versions_menu/issues/18
.. _conda-feedstock: https://github.com/conda-forge/doctr-versions-menu-feedstock#readme
نیازمندی
| مقدار | نام |
|---|---|
| >=6.7 | click |
| >=5.0.6 | configobj |
| - | doctr |
| - | packaging |
| >=2.0.2 | pyparsing |
| - | setuptools |
| - | sphinx |
| - | coverage |
| - | coveralls |
| - | flake8 |
| - | gitpython |
| - | ipython |
| - | isort |
| - | pdbpp |
| - | pre-commit |
| - | pylint |
| - | pytest |
| - | pytest-cov |
| - | pytest-xdist |
| - | sphinx |
| - | sphinx-autobuild |
| - | sphinx-autodoc-typehints |
| - | sphinx-copybutton |
| - | sphinx-rtd-theme |
| - | travis-encrypt |
| - | twine |
| - | wheel |
| - | black |
زبان مورد نیاز
| مقدار | نام |
|---|---|
| >=3.5 | Python |
نحوه نصب
نصب پکیج whl doctr-versions-menu-0.4.1:
pip install doctr-versions-menu-0.4.1.whl
نصب پکیج tar.gz doctr-versions-menu-0.4.1:
pip install doctr-versions-menu-0.4.1.tar.gz