{"id":20210788,"url":"https://github.com/bluekeyes/sphinx-javalink","last_synced_at":"2025-04-10T13:21:43.894Z","repository":{"id":26274765,"uuid":"29722183","full_name":"bluekeyes/sphinx-javalink","owner":"bluekeyes","description":"Link to Javadoc APIs from Sphinx documentation","archived":false,"fork":false,"pushed_at":"2016-01-14T07:13:38.000Z","size":56,"stargazers_count":8,"open_issues_count":0,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-24T12:06:13.600Z","etag":null,"topics":["javadoc","python","sphinx","sphinx-doc","sphinx-extension"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bluekeyes.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-01-23T07:41:57.000Z","updated_at":"2023-02-13T21:07:52.000Z","dependencies_parsed_at":"2022-08-26T21:12:46.020Z","dependency_job_id":null,"html_url":"https://github.com/bluekeyes/sphinx-javalink","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluekeyes%2Fsphinx-javalink","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluekeyes%2Fsphinx-javalink/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluekeyes%2Fsphinx-javalink/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluekeyes%2Fsphinx-javalink/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bluekeyes","download_url":"https://codeload.github.com/bluekeyes/sphinx-javalink/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248225661,"owners_count":21068078,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javadoc","python","sphinx","sphinx-doc","sphinx-extension"],"created_at":"2024-11-14T05:49:28.432Z","updated_at":"2025-04-10T13:21:43.874Z","avatar_url":"https://github.com/bluekeyes.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"***************\nsphinx-javalink\n***************\n\nA Sphinx_ extension for linking to ``javadoc``-generated API documentation.\n\n.. _Sphinx: http://sphinx-doc.org/\n\n.. contents::\n   :local:\n   :depth: 1\n   :backlinks: none\n\nInstallation\n============\n\n``sphinx-javalink`` is availabe from PyPI_:\n\n.. code-block:: console\n\n    pip install sphinx-javalink\n\n.. _PyPI: https://pypi.python.org/pypi/sphinx-javalink\n\nUsage\n=====\n\nUse the ``javaref`` role to link to Java types, members, and packages:\n\n.. code-block:: rst\n\n    Alpacas are best stored in a :javaref:`java.util.HashMap`, while clients\n    may find that goats perform best in a :javaref:`java.util.TreeMap`. In\n    either case, use :javaref:`biz.cloudgoats.api.Wizard#convert(Object)` to\n    produce legally binding contracts.\n\n    For more details, see the :javaref:`biz.cloudgoats.api` package.\n\nReference targets use standard Javadoc ``@see`` and ``@link`` syntax_.\nReference titles are generated based on the configuration options described\nbelow. To use an explicit title, place the Java reference in angle brackets\nfollowing the title:\n\n.. code-block:: rst\n\n    :javaref:`I like objects! \u003cjava.lang.Object\u003e`\n\nBy default, references must be fully qualified. For convenience, use the\n``javaimport`` directive to import commonly used types:\n\n.. code-block:: rst\n\n    .. javaimport::\n       java.util.*\n       biz.cloudgoats.api.Wizard\n\n    Alpacas are best stored in a :javaref:`HashMap`, while clients may find\n    that goats perform best in a :javaref:`TreeMap`. In either case, use\n    :javaref:`Wizard#convert(Object)` to produce chocolate covered pebbles or\n    peanuts, depending on environmental factors.\n\n    For more details, see the :javaref:`biz.cloudgoats.api` package.\n\nEach import appears on its own line and may be either a type or a package name\nfollowed by a ``*``. As in Java, this imports all types in the package. All\ntypes in the ``java.lang`` package are imported by default.\n\nThe ``javaimport`` directive must appear before the first ``javaref`` that uses\none of the imported types. A document can have multiple ``javaimport``\ndirectives; the imports are cumulative.\n\n.. _syntax: http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#see\n\nExamples\n========\n\nA simple example_ ``conf.py`` is included in the repository. For real-world\nexamples, see these projects:\n\n- Giraffe_\n\n.. _example: examples/conf.py\n.. _Giraffe: https://github.com/palantir/giraffe\n\nConfiguration\n=============\n\n``javalink_classpath``\n^^^^^^^^^^^^^^^^^^^^^^\n\n*Default:* ``[]``\n\nA list of jar files and directories in which to search for classes.  Elements\ncan take one of three forms:\n\n1. ``/path/to/library.jar`` - an absolute or relative path to a jar file\n2. ``/path/to/classes/dir`` - an absolute or relative path a directory\n   containing class files\n3. ``/path/to/jar/dir/*`` - an absolute or relative path a directory containing\n   jar files. Only jar files that are direct children of the directory are\n   loaded.\n\nAll relative paths are relative to the source directory.\n\nTo link to classes in the standard library, ``rt.jar`` (shipped with the JRE)\nmust be on the class path. Use ``javalink.find_rt_jar()`` to find the location\nof this jar on the local system. This function respects the ``JAVA_HOME``\nenvironment variable and may optionally take the path to an alternative\ndirectory as an argument.\n\n``javalink_docroots``\n^^^^^^^^^^^^^^^^^^^^^\n\n*Default:* ``[]``\n\nA list of Javadocs that can be the target of links. A valid |package-list|_\nfile must exist in the directory specified by the root path or URL.\n\nList elements may be either:\n\n1. A string\n2. A dictionary with the following keys:\n\n   - ``root`` (string, required)\n   - ``base`` (string, optional)\n   - ``version`` (integer, optional)\n\nProviding a string is equivalent to providing a dictionary with only the\n``root`` key.\n\n``root`` is a path or URL used to fine the ``package-list`` file. ``base`` is\nthe base component of generated links; if it is not specified, the value of\n``root`` is used. ``version`` is the version of the ``javadoc`` tool used to\ngenerate the documentation; if it is not specified, the value of\n``javalink_default_version`` is used.\n\nSpecifying a ``base`` that differs from ``root`` is useful when the\n``package-list`` is available at a local path that is not available from the\nbuilt and published documentation. This also allows offline builds, by\ndownloading all remote ``package-list`` files ahead of time.\n\n.. |package-list| replace:: ``package-list``\n.. _package-list: http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#linkpackagelist\n\n``javalink_default_version``\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n*Default:* ``7``\n\nThe version of the ``javadoc`` tool assumed if a version is not provided for a\ndocroot. The version determines the format of generated links, which was\nchanged in Java 8.\n\n``javalink_add_method_parameters``\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n*Default:* ``True``\n\nA boolean that determines if parameter lists and parentheses are appended to\ngenerated method references. References with explicit titles are not modified.\n\n``javalink_add_package_names``\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n*Default:* ``True``\n\nA boolean that determines if fully-qualified package names are prepended to\ngenerated references. References with explicit titles are not modified.\n\n``javalink_qualify_nested_types``\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n*Default:* ``True``\n\nA boolean that determines if containing type names are prepended to generated\nreferences to nested types. Only applies if ``javalink_add_package_names`` is\n``False``. References with explicit titles are not modified.\n\nLimitations and Known Issues\n============================\n\n- When linking to methods, only the types of arguments may be specified.\n  Specifying argument names will produce incorrect results.\n- All references are created as ``literal`` nodes.\n\nRequirements\n============\n\n- Python 2.7 (no support for Python 3)\n- Sphinx\n- `javatools \u003chttps://github.com/obriencj/python-javatools\u003e`_\n\nContributing\n============\n\nPull requests, bug reports, and feature requests are welcome.\n\nLicense\n=======\n\n`MIT \u003chttp://opensource.org/licenses/MIT\u003e`_, see the ``LICENSE`` file.\n\nChangelog\n=========\n\n**0.11.1** (2016-01-13)\n\n- Open resources lazily\n- Fix incorrect environment cache invalidation\n- Fix potential ordering issues with Sphinx events (thanks to @rlepinski)\n\n**0.11.0** (2015-12-13)\n\n- Significantly improve performance (10x speedup in testing)\n\n  - Cache missing classes (thanks to @rlepinski)\n  - Open all resources at startup instead of reopening for every class search\n\n- Fix reporting of invalid references for class paths with class files\n\n**0.10.2** (2015-12-02)\n\n- Support linking to overloaded methods (thanks to @thasso)\n\n**0.10.1** (2015-09-02)\n\n- Fix syntax error in ``env-merge-info`` hook (thanks to @dadouf)\n\n**0.10.0** (2015-08-30)\n\n- Support the ``env-merge-info`` hook\n- Fix #5 - support Java 8 link formats; required a breaking change to the\n  ``javalink_docroots`` syntax (thanks to @dadouf)\n\n**0.9.2** (2015-03-08)\n\n- Fix #3 - resolve paths relative to the source directory\n\n**0.9.1** (2015-03-03)\n\n- Fix #2 - correctly generate links to varargs methods\n- Fix #1 - ``find_rt_jar()`` now works correctly on OS X\n\n**0.9.0** (2015-01-25)\n\n- Initial release\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluekeyes%2Fsphinx-javalink","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbluekeyes%2Fsphinx-javalink","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluekeyes%2Fsphinx-javalink/lists"}