Write

Deprecated since version 1.5.0: write rst is deprecated and will be removed in Sphinx-CodeLinks 2.0.0. The Sphinx build attaches @need-ids: references to the needs they name itself, in each project’s ref_url_field (default code_url): see Need ID references in the build, which also says how to migrate. The command still works, and prints a notice on stderr.

The write command is used to generate file formats such as reStructuredText from the markers extracted by the analyse command. This allows you to create documentation that includes links to source code based on the need ids specified in your code comments.

Example usage

With the following extracted markers fron the analyse command,

{
    "my_project": [
        {
            "filepath": "/home/demo/git_repo/ub/sphinx-codelinks/tests/data/need_id_refs/dummy_1.cpp",
            "remote_url": "https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3",
            "source_map": {
                "start": {"row": 2, "column": 14},
                "end": {"row": 2, "column": 52}
            },
            "tagged_scope": "void dummy_func1(){\n     //...\n }",
            "need_ids": ["NEED_001", "NEED_002", "NEED_003", "NEED_004"],
            "marker": "@need-ids:",
            "type": "need-id-refs"
        },
    ],
}

The following RST file with needextend directive can be generated by the write rst command:

.. needextend:: NEED_001
       :remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3

.. needextend:: NEED_002
       :remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3

.. needextend:: NEED_003
       :remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3

.. needextend:: NEED_004
       :remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3

More examples can be found in test cases