Skip to content
Back to top
View this page
Edit this page

# Sphinx-Data-Viewer

A simple data viewer for data of type json or python object, which shows the data in an interactive list-view on HTML pages.

Show source code for above example

    .. data-viewer::
       :expand:

       {
         "Peter Meister": {
           "firstname": "Peter",
           "surname": "Meister",
           "is_female": false,
           "city": "Munich",
           "age": 26,
           "height_m": 1.86,
           "nicknames": ["Peti", "Pet", "Bomber"]
         },
         "Sandra Wilson": {
           "firstname": "Sandra",
           "surname": "Wilson",
           "is_female": true,
           "city": "London",
           "age": 32,
           "height_m": 1.67,
           "nicknames": ["Sandy", "Wilma"]
         }
       }

Supports data from `data-viewer` content, files or variables from a `conf.py` configuration.

## Installation

Use `pip` to install `Sphinx-Data-Viewer`

    pip install sphinx-data-viewer

Then add it to the extensions of your `conf.py` file

    extensions = [
        "sphinx_data_viewer",
    ]

## Options

### title

Sets a title in front of the data representation.

Default: None

Code

    .. data-viewer::
       :title: My first data viewer example

       ["apple", "orange", "banana"]

Result

My first data viewer example

### expand

Use `expand` to show the complete data.

`expand` does not need any value, as it is a flag and its usage is enough to set it to True.

Default: False (not set)

Code

    .. data-viewer::
       :expand:

       {
          "Peter Meister": {
             "firstname": "Peter",
             "surname": "Meister",
             "city": "Munich",
             "age": 26,
             "height_m": 1.86,
             "nicknames": ["Peti", "Pet", "Bomber"]
          },
          "Sandra Wilson": {
             "firstname": "Sandra",
             "surname": "Wilson",
             "city": "London",
             "age": 32,
             "height_m": 1.67,
             "nicknames": ["Sandy", "Wilma"]
          }
       }

Result

### file

Use `file` to load data from a file.

`file` takes an absolute or relative path. If it is relative, an absolut path gets calculated based on current document path.

Default: None

Code

    .. data-viewer::
       :file: test.json

Data

    [
      {
        "_id": "61a0891a674f1c06f0477709",
        "index": 0,
        "guid": "7f878bf5-1b9c-4272-b6ed-00cbd37f8b1d",
        "isActive": true,
        "balance": "$1,499.41",
        "picture": "http://placehold.it/32x32",
        "age": 26,
        "eyeColor": "blue",
        "name": "Kristi Jefferson",
        "gender": "female",
        "company": "ZILLATIDE",
        "email": "kristijefferson@zillatide.com",
        "phone": "+1 (983) 481-2169",
        "address": "451 Marconi Place, Temperanceville, Missouri, 3245",
        "about": "Sint ipsum voluptate pariatur sunt est ad deserunt commodo mollit reprehenderit minim tempor mollit ipsum. Minim mollit nulla aliqua dolor nulla. Laboris duis fugiat et officia amet quis voluptate officia ullamco id. Enim consectetur anim culpa sint sunt ipsum elit do incididunt nostrud elit amet culpa ad.\r\n",
        "registered": "2014-01-16T10:48:53 -01:00",
        "latitude": -49.997781,
        "longitude": 10.96195,
        "tags": [
          "nulla",
          "duis",
          "irure",
          "anim",
          "nulla",
          "dolor",
          "est"
        ],
        "friends": [
          {
            "id": 0,
            "name": "Leticia Garcia"
          },
          {
            "id": 1,
            "name": "Hobbs Sanchez"
          },
          {
            "id": 2,
            "name": "Keri Elliott"
          }
        ],
        "favoriteFruit": "apple"
      },
      {
        "_id": "61a0891af9959181625ac7dc",
        "index": 1,
        "guid": "3fa0ed52-7d1f-43e1-8ce6-78b605f6b62f",
        "isActive": true,
        "balance": "$2,960.79",
        "picture": "http://placehold.it/32x32",
        "age": 32,
        "eyeColor": "blue",
        "name": "Coffey Beach",
        "gender": "male",
        "company": "BUZZNESS",
        "email": "coffeybeach@buzzness.com",
        "phone": "+1 (861) 583-2393",
        "address": "187 Tabor Court, Hemlock, Federated States Of Micronesia, 5566",
        "about": "Do excepteur excepteur aliquip sint sit pariatur dolore ullamco laboris. Eiusmod qui adipisicing excepteur anim cillum anim in velit id. Veniam cillum minim amet amet reprehenderit irure esse. Aliquip eu ullamco et ex anim. Irure ea dolore ad consectetur laboris consequat mollit eu irure in sit magna consequat. Eu nisi do labore est Lorem aute ea est enim Lorem et veniam sit nisi.\r\n",
        "registered": "2020-02-12T12:19:06 -01:00",
        "latitude": 69.935896,
        "longitude": -107.458737,
        "tags": [
          "enim",
          "cillum",
          "dolor",
          "labore",
          "elit",
          "cupidatat",
          "sit"
        ],
        "friends": [
          {
            "id": 0,
            "name": "Holcomb Adkins"
          },
          {
            "id": 1,
            "name": "Taylor Black"
          },
          {
            "id": 2,
            "name": "Jennie Ashley"
          }
        ],
        "favoriteFruit": "strawberry"
      },
      {
        "_id": "61a0891ae91cc10ea4a169ac",
        "index": 2,
        "guid": "b63c69bc-f8df-4bee-ba52-c621ec841ea9",
        "isActive": true,
        "balance": "$3,209.24",
        "picture": "http://placehold.it/32x32",
        "age": 28,
        "eyeColor": "brown",
        "name": "Lara Donaldson",
        "gender": "male",
        "company": "RODEOLOGY",
        "email": "laradonaldson@rodeology.com",
        "phone": "+1 (970) 547-2377",
        "address": "195 Main Street, Snelling, Kansas, 1379",
        "about": "Quis minim dolor anim non qui. Culpa eiusmod incididunt veniam excepteur magna voluptate aute. Sunt magna tempor non quis aliqua eiusmod eiusmod duis et. Sunt sit occaecat excepteur deserunt pariatur adipisicing mollit. Et ipsum adipisicing magna dolor commodo veniam culpa incididunt culpa. Mollit veniam fugiat cupidatat est excepteur. Do pariatur eiusmod in qui quis laboris sint ullamco tempor nostrud ut.\r\n",
        "registered": "2017-08-24T03:13:21 -02:00",
        "latitude": -27.717817,
        "longitude": -22.673387,
        "tags": [
          "veniam",
          "laborum",
          "nulla",
          "sit",
          "aliquip",
          "consectetur",
          "velit"
        ],
        "friends": [
          {
            "id": 0,
            "name": "Stefanie Ayers"
          },
          {
            "id": 1,
            "name": "Bryan Cervantes"
          },
          {
            "id": 2,
            "name": "James Todd"
          }
        ],
        "favoriteFruit": "strawberry"
      },
      {
        "_id": "61a0891a1a6ee5b221c88f1a",
        "index": 3,
        "guid": "8ce04bb5-52df-426d-8cce-57c97fe0f5e2",
        "isActive": false,
        "balance": "$2,357.08",
        "picture": "http://placehold.it/32x32",
        "age": 36,
        "eyeColor": "green",
        "name": "Felicia Meyer",
        "gender": "female",
        "company": "SECURIA",
        "email": "feliciameyer@securia.com",
        "phone": "+1 (887) 542-2830",
        "address": "844 Kosciusko Street, Goodville, Wyoming, 1447",
        "about": "Commodo minim amet pariatur ex ut occaecat enim velit. Sit est et voluptate exercitation. Id enim ipsum non laboris aute pariatur fugiat quis. Dolor esse esse labore laboris ex labore nulla incididunt laborum pariatur ipsum ipsum incididunt non.\r\n",
        "registered": "2015-01-20T12:02:20 -01:00",
        "latitude": 18.318437,
        "longitude": 12.216479,
        "tags": [
          "non",
          "ad",
          "aliqua",
          "adipisicing",
          "reprehenderit",
          "incididunt",
          "excepteur"
        ],
        "friends": [
          {
            "id": 0,
            "name": "Trudy Valentine"
          },
          {
            "id": 1,
            "name": "Dennis Hebert"
          },
          {
            "id": 2,
            "name": "Rush Weaver"
          }
        ],
        "favoriteFruit": "banana"
      },
      {
        "_id": "61a0891a52b8a601e208625a",
        "index": 4,
        "guid": "5652f03a-8fc9-4bdf-8546-d6cb60b960e5",
        "isActive": true,
        "balance": "$2,587.43",
        "picture": "http://placehold.it/32x32",
        "age": 33,
        "eyeColor": "green",
        "name": "Walter Lindsay",
        "gender": "male",
        "company": "PRIMORDIA",
        "email": "walterlindsay@primordia.com",
        "phone": "+1 (906) 573-2128",
        "address": "497 Jackson Place, Stollings, Connecticut, 3285",
        "about": "Reprehenderit enim consequat consequat duis. Id reprehenderit laborum minim commodo incididunt sint laboris est ut magna qui aliquip est. Et ad aliquip tempor excepteur in eiusmod aliqua culpa sint quis. Laboris amet ea id voluptate minim nostrud dolore in voluptate enim irure amet et.\r\n",
        "registered": "2020-10-11T04:13:15 -02:00",
        "latitude": 55.769158,
        "longitude": 93.670297,
        "tags": [
          "eiusmod",
          "mollit",
          "reprehenderit",
          "voluptate",
          "nulla",
          "eiusmod",
          "consequat"
        ],
        "friends": [
          {
            "id": 0,
            "name": "Polly Suarez"
          },
          {
            "id": 1,
            "name": "Mcbride Holden"
          },
          {
            "id": 2,
            "name": "Odonnell Mcknight"
          }
        ],
        "favoriteFruit": "banana"
      },
      {
        "_id": "61a0891a508c2aefb2397c68",
        "index": 5,
        "guid": "fe44f736-7650-4927-b2b7-e59d04446439",
        "isActive": true,
        "balance": "$2,373.99",
        "picture": "http://placehold.it/32x32",
        "age": 39,
        "eyeColor": "brown",
        "name": "Lester Lewis",
        "gender": "male",
        "company": "PHORMULA",
        "email": "lesterlewis@phormula.com",
        "phone": "+1 (844) 462-2212",
        "address": "330 Willow Street, Seymour, Virgin Islands, 6905",
        "about": "Duis consequat tempor est Lorem qui non dolore aliquip est adipisicing. Do aliqua quis ut nulla aute cillum et. Et amet culpa ex nisi. Laborum ad laborum officia Lorem. Deserunt incididunt officia tempor amet culpa consectetur incididunt reprehenderit ad non ipsum occaecat. Anim ipsum exercitation incididunt Lorem.\r\n",
        "registered": "2015-01-10T08:36:40 -01:00",
        "latitude": -49.099774,
        "longitude": -103.954882,
        "tags": [
          "nostrud",
          "eiusmod",
          "adipisicing",
          "occaecat",
          "officia",
          "aliqua",
          "in"
        ],
        "friends": [
          {
            "id": 0,
            "name": "Sheena Kinney"
          },
          {
            "id": 1,
            "name": "Marva Dennis"
          },
          {
            "id": 2,
            "name": "Leigh Bender"
          }
        ],
        "favoriteFruit": "apple"
      },
      {
        "_id": "61a0891a05517b2d5083116a",
        "index": 6,
        "guid": "9c96d7bc-559b-46d0-a1ad-1b3b7f51e466",
        "isActive": false,
        "balance": "$2,718.32",
        "picture": "http://placehold.it/32x32",
        "age": 40,
        "eyeColor": "brown",
        "name": "Benson Mcconnell",
        "gender": "male",
        "company": "OPTICOM",
        "email": "bensonmcconnell@opticom.com",
        "phone": "+1 (919) 465-2279",
        "address": "618 Bills Place, Jugtown, Palau, 7788",
        "about": "Cillum magna Lorem cillum irure et nulla elit exercitation. Excepteur exercitation exercitation duis culpa ut aliqua ullamco aliqua nisi incididunt exercitation exercitation dolor. Deserunt non enim aute sint sunt id dolore nulla eu cupidatat. Est adipisicing quis enim sint enim veniam ut irure eiusmod ex anim. Ullamco id minim ea mollit qui id.\r\n",
        "registered": "2020-06-14T09:45:04 -02:00",
        "latitude": -22.541407,
        "longitude": 172.579385,
        "tags": [
          "velit",
          "consectetur",
          "esse",
          "anim",
          "adipisicing",
          "aute",
          "reprehenderit"
        ],
        "friends": [
          {
            "id": 0,
            "name": "Bettie Harrington"
          },
          {
            "id": 1,
            "name": "Terry Roach"
          },
          {
            "id": 2,
            "name": "Bird Davidson"
          }
        ],
        "favoriteFruit": "strawberry"
      },
      {
        "_id": "61a0891a8c08c1713d406db6",
        "index": 7,
        "guid": "c8f79b2a-7cd0-492d-957c-f5cdd089d6a4",
        "isActive": false,
        "balance": "$1,926.46",
        "picture": "http://placehold.it/32x32",
        "age": 29,
        "eyeColor": "brown",
        "name": "Alvarado Melendez",
        "gender": "male",
        "company": "CHILLIUM",
        "email": "alvaradomelendez@chillium.com",
        "phone": "+1 (800) 442-3551",
        "address": "103 Ludlam Place, Bainbridge, Georgia, 6493",
        "about": "Quis labore aliqua dolor reprehenderit cupidatat. Adipisicing anim irure velit commodo fugiat velit laboris cillum fugiat deserunt. Non do sunt consectetur aliquip commodo deserunt commodo pariatur dolor deserunt. Aute ea culpa laborum enim aute ipsum. Consectetur ipsum ex aliqua ex irure qui occaecat. Aute id duis laboris quis ullamco amet veniam voluptate eiusmod reprehenderit aute non. Incididunt labore occaecat culpa ullamco ut exercitation pariatur duis enim velit laboris aliqua eu sint.\r\n",
        "registered": "2021-06-10T01:25:33 -02:00",
        "latitude": 11.792983,
        "longitude": 5.604258,
        "tags": [
          "ea",
          "do",
          "minim",
          "esse",
          "ipsum",
          "sint",
          "ut"
        ],
        "friends": [
          {
            "id": 0,
            "name": "Mcmahon Wilkerson"
          },
          {
            "id": 1,
            "name": "Susanne Cotton"
          },
          {
            "id": 2,
            "name": "Walsh Chavez"
          }
        ],
        "favoriteFruit": "banana"
      },
      {
        "_id": "61a0891ab564605bf251d75c",
        "index": 8,
        "guid": "622dceb8-895a-440d-b33a-e1ef21d1e6d2",
        "isActive": true,
        "balance": "$2,202.26",
        "picture": "http://placehold.it/32x32",
        "age": 34,
        "eyeColor": "brown",
        "name": "Elisabeth Strickland",
        "gender": "female",
        "company": "AQUOAVO",
        "email": "elisabethstrickland@aquoavo.com",
        "phone": "+1 (917) 501-3354",
        "address": "117 Jerome Street, Springville, Delaware, 7395",
        "about": "Id sit consectetur est pariatur ipsum minim quis nulla eiusmod nulla magna commodo sint. Minim commodo elit minim mollit cupidatat quis minim. Duis commodo ullamco id pariatur enim. Adipisicing ad labore amet eu aute.\r\n",
        "registered": "2016-03-19T03:48:29 -01:00",
        "latitude": -32.551099,
        "longitude": -163.296924,
        "tags": [
          "tempor",
          "enim",
          "sit",
          "ea",
          "cupidatat",
          "velit",
          "aliqua"
        ],
        "friends": [
          {
            "id": 0,
            "name": "Joyce Shaffer"
          },
          {
            "id": 1,
            "name": "Simon Riggs"
          },
          {
            "id": 2,
            "name": "Jackie Kennedy"
          }
        ],
        "favoriteFruit": "strawberry"
      },
      {
        "_id": "61a0891a74a88c306c3177fa",
        "index": 9,
        "guid": "92b96807-c152-4cdf-ac31-2daa44e859a6",
        "isActive": false,
        "balance": "$3,288.68",
        "picture": "http://placehold.it/32x32",
        "age": 29,
        "eyeColor": "green",
        "name": "Luz Bridges",
        "gender": "female",
        "company": "COMTRAIL",
        "email": "luzbridges@comtrail.com",
        "phone": "+1 (883) 406-2760",
        "address": "273 Locust Avenue, Juarez, Virginia, 6678",
        "about": "Duis proident ullamco fugiat aute mollit enim commodo. In tempor in tempor ex ex id incididunt esse do ea in reprehenderit. Ad anim dolor eu non excepteur sint eu anim ea dolor. Aute laborum occaecat reprehenderit culpa enim.\r\n",
        "registered": "2014-02-11T01:25:36 -01:00",
        "latitude": -56.063378,
        "longitude": 4.041166,
        "tags": [
          "laborum",
          "anim",
          "duis",
          "mollit",
          "ullamco",
          "consectetur",
          "consequat"
        ],
        "friends": [
          {
            "id": 0,
            "name": "Debbie Price"
          },
          {
            "id": 1,
            "name": "Bradley Knowles"
          },
          {
            "id": 2,
            "name": "Alana Finley"
          }
        ],
        "favoriteFruit": "strawberry"
      },
      {
        "_id": "61a0891aefee64076b42a964",
        "index": 10,
        "guid": "2dce2979-0e6b-4df1-95e9-3afef537e635",
        "isActive": true,
        "balance": "$2,029.23",
        "picture": "http://placehold.it/32x32",
        "age": 40,
        "eyeColor": "brown",
        "name": "Greene Carpenter",
        "gender": "male",
        "company": "KOFFEE",
        "email": "greenecarpenter@koffee.com",
        "phone": "+1 (848) 405-3406",
        "address": "658 Cortelyou Road, Clay, Rhode Island, 9355",
        "about": "Minim nostrud non deserunt adipisicing excepteur ullamco. Ex mollit pariatur reprehenderit elit ullamco est irure officia culpa id. Lorem eu Lorem ut dolore minim cupidatat. Exercitation culpa pariatur in exercitation nulla laboris minim do qui consectetur deserunt culpa nulla incididunt. Esse veniam reprehenderit Lorem eu proident officia duis officia in aliqua eiusmod. Minim cillum exercitation laboris ea est sint dolor ipsum.\r\n",
        "registered": "2014-08-31T06:52:58 -02:00",
        "latitude": -29.658821,
        "longitude": 71.814451,
        "tags": [
          "cupidatat",
          "ipsum",
          "ipsum",
          "ipsum",
          "cillum",
          "Lorem",
          "sunt"
        ],
        "friends": [
          {
            "id": 0,
            "name": "Haley Richmond"
          },
          {
            "id": 1,
            "name": "Rogers Case"
          },
          {
            "id": 2,
            "name": "Hewitt Fisher"
          }
        ],
        "favoriteFruit": "strawberry"
      },
      {
        "_id": "61a0891a6e0a0070b0863f7c",
        "index": 11,
        "guid": "8c55ee96-81b4-46a2-8555-1d65566475da",
        "isActive": true,
        "balance": "$3,006.50",
        "picture": "http://placehold.it/32x32",
        "age": 36,
        "eyeColor": "brown",
        "name": "Selma Terrell",
        "gender": "female",
        "company": "EARTHPLEX",
        "email": "selmaterrell@earthplex.com",
        "phone": "+1 (920) 520-3529",
        "address": "194 Adelphi Street, Mayfair, North Dakota, 546",
        "about": "Ex nostrud aute officia magna laboris mollit sit aliqua qui incididunt voluptate. Dolore anim sunt duis ut eiusmod ex qui. Id quis cillum Lorem esse do exercitation esse sunt nisi voluptate sit non. Reprehenderit voluptate deserunt nisi consectetur deserunt aute ea aliquip eu.\r\n",
        "registered": "2020-03-10T01:47:01 -01:00",
        "latitude": -47.548179,
        "longitude": 117.412115,
        "tags": [
          "minim",
          "in",
          "exercitation",
          "minim",
          "veniam",
          "occaecat",
          "nulla"
        ],
        "friends": [
          {
            "id": 0,
            "name": "Hahn Brennan"
          },
          {
            "id": 1,
            "name": "Raquel Tran"
          },
          {
            "id": 2,
            "name": "Bradshaw Winters"
          }
        ],
        "favoriteFruit": "banana"
      },
      {
        "_id": "61a0891a2b62527ed7cdf215",
        "index": 12,
        "guid": "ca32e606-24e0-4a8d-8436-3ae18457eb19",
        "isActive": false,
        "balance": "$1,804.99",
        "picture": "http://placehold.it/32x32",
        "age": 28,
        "eyeColor": "blue",
        "name": "Mckinney Mcmillan",
        "gender": "male",
        "company": "PULZE",
        "email": "mckinneymcmillan@pulze.com",
        "phone": "+1 (850) 401-3836",
        "address": "164 Knickerbocker Avenue, Virgie, Colorado, 5807",
        "about": "Dolore aute deserunt in eu enim sint est ipsum fugiat pariatur sunt nisi eu ea. Occaecat aute veniam adipisicing ad sunt est quis veniam eiusmod consequat fugiat commodo. Commodo elit aliqua nisi cillum quis quis laboris minim dolor magna id in.\r\n",
        "registered": "2019-12-09T04:12:53 -01:00",
        "latitude": 38.619051,
        "longitude": 31.515656,
        "tags": [
          "quis",
          "dolore",
          "ullamco",
          "excepteur",
          "reprehenderit",
          "in",
          "ad"
        ],
        "friends": [
          {
            "id": 0,
            "name": "Cleveland Lamb"
          },
          {
            "id": 1,
            "name": "Kerr Vasquez"
          },
          {
            "id": 2,
            "name": "Dorsey Campos"
          }
        ],
        "favoriteFruit": "banana"
      },
      {
        "_id": "61a0891a8bc3ddae13479c18",
        "index": 13,
        "guid": "8ea88318-e049-4de6-ac0e-99ed0a87afa1",
        "isActive": false,
        "balance": "$2,233.27",
        "picture": "http://placehold.it/32x32",
        "age": 28,
        "eyeColor": "blue",
        "name": "Hazel Campbell",
        "gender": "female",
        "company": "HOMELUX",
        "email": "hazelcampbell@homelux.com",
        "phone": "+1 (821) 451-2983",
        "address": "374 Maujer Street, Cetronia, Oregon, 9926",
        "about": "Dolore ut elit minim proident excepteur excepteur magna cillum officia adipisicing proident deserunt. Consectetur ipsum minim ex elit. Ut consequat ut nostrud aliqua fugiat in esse tempor qui.\r\n",
        "registered": "2015-02-18T11:25:44 -01:00",
        "latitude": -24.219396,
        "longitude": 47.247109,
        "tags": [
          "magna",
          "eiusmod",
          "dolore",
          "labore",
          "est",
          "in",
          "nulla"
        ],
        "friends": [
          {
            "id": 0,
            "name": "Eddie Ortiz"
          },
          {
            "id": 1,
            "name": "Lena Gillespie"
          },
          {
            "id": 2,
            "name": "Cummings Heath"
          }
        ],
        "favoriteFruit": "apple"
      },
      {
        "_id": "61a0891a55c66f848a09012b",
        "index": 14,
        "guid": "0c6f1ca4-9409-403c-a2f8-05cf6557fd1f",
        "isActive": true,
        "balance": "$3,372.21",
        "picture": "http://placehold.it/32x32",
        "age": 24,
        "eyeColor": "blue",
        "name": "Irma Stevens",
        "gender": "female",
        "company": "GENEKOM",
        "email": "irmastevens@genekom.com",
        "phone": "+1 (936) 539-2186",
        "address": "499 Sutton Street, Savannah, New Mexico, 5482",
        "about": "Aute aliqua esse aute magna eu nostrud incididunt id nulla ea irure incididunt sunt. Reprehenderit ipsum sunt sint est sunt ullamco ad mollit incididunt est velit ad dolore sunt. Mollit anim ipsum sint elit ea. Tempor culpa deserunt minim fugiat anim commodo aliquip est occaecat. Ex mollit laboris pariatur ullamco ex ex laboris est adipisicing est sunt.\r\n",
        "registered": "2020-04-22T12:38:00 -02:00",
        "latitude": -39.660368,
        "longitude": 162.640521,
        "tags": [
          "laborum",
          "laboris",
          "irure",
          "do",
          "enim",
          "dolor",
          "nulla"
        ],
        "friends": [
          {
            "id": 0,
            "name": "Sharlene Flores"
          },
          {
            "id": 1,
            "name": "Graham Britt"
          },
          {
            "id": 2,
            "name": "Jeannie Oneal"
          }
        ],
        "favoriteFruit": "strawberry"
      }
    ]

Result

### data

`data` defines a key, which is taken to look up for data in the configuration variable `data_viewer_data`.

Default: None

Code

    .. data-viewer::
       :data: my_data

Config

    # Inside conf.py

    data_viewer_data = {
        "my_data": {
            "name": "Mario",
            "job": "plumber",
            "magic_tubes": [2, 7, 23, 43.5]
        }
    }

Result

## Errors

The data must be always valid json-data, if it is coming from the content of `data-viewer` or if it gets read from a file.

If `data` option is used to read data from the `data_viewer_data` option of your `conf.py`, this referenced object gets loaded via `json.dumps()`, so that the object must be serializable.

Parsing exception can happen during Sphinx-Build and in the used JavaScript code when the browser loads the page.

If the JavaScript code detects problems, some error text gets printed on the webpage.

Result

Problem: Missing `,` after `"Peter"`

Code

    Problem: Missing `,` after `"Peter"`

    .. data-viewer::

       {
         "name": "Peter"
         "user": "peterbomber"
       }

## Works well with…

Here are some ideas and examples, how `data-viewer` could be used together with other Sphinx extensions.

### Sphinx-Needs

Use Sphinx-Needs to define process elements like requirements and specifications. And `Sphinx-Data-Viewer` to explain data structures more easily.

Result

Specification: /api/user return value SPEC_001
status: open tags: endpoint, user
For our API endpoint `/api/user` the default data structure of the return value of a successful GET request shall look like:

Code

    .. spec:: /api/user return value
       :id: SPEC_001
       :tags: endpoint, user
       :status: open

       For our API endpoint ``/api/user`` the default data structure of the return value of a successful GET
       request shall look like:

       .. data-viewer::
          :expand:

          {
             "username": "peterbomber",
             "email": "peterbomber@my_company.net",
             "active": true
          }

### Sphinx-Design

Sphinx-Design can be used to bring cards, tabs and dropdowns into your documentation. It can help you to show source code or the data-viewer on user requests only.

All the dropdowns and tabs on this side got realised by `Sphinx-Design`.

Take a look into the current page source for a bunch of examples.

Result

Data-Viewer 1

Data-Viewer 2

Code

    .. grid:: 2

        .. grid-item-card::

           Data-Viewer 1
           ^^^^^^^^^^^^^

           .. data-viewer::
              :expand:

              {
                 "name": "Peter",
                 "pets": ["dog", "cat"]
              }

        .. grid-item-card::

           Data-Viewer 2
           ^^^^^^^^^^^^^

           .. data-viewer::
              :expand:

              {
                 "name": "Sandra",
                 "pets": ["squirrel"]
              }

## License

This software project is released under the MIT license.

See LICENSE file for more details.

## API

Small API to create Data-Viewer nodes from other Sphinx extensions

sphinx_data_viewer.api.get_data_viewer_node(title, data, expand=True)

  Returns a docutils node, which represents a configured data-viewer.

  Parameters:

    - title – Title for the viewer as string

    - data – Data as python objects, which must be serializable by json.dumps()

    - expand – True or False as boolean. If True all data will be shown.

  Returns:

    Configured DataViewerNode instance

## Kudos

The javascript code is based on the wonderful work of https://github.com/pgrabovets/json-view.

## Changelog

### 0.1.4

released:

  25.1.2024

- Bugfix: Fix for builders, which do not support registration of CSS/JS files (e.g. sphinxcontrib-spelling)

### 0.1.3

released:

  25.1.2024

- Improvement: Updated project documentation to use the useblocks theme.

- Bugfix: Avoids multiple registrations of the same CSS/JS file.

### 0.1.2

released:

  07.12.2021

- Bugfix: Fixed wrong handling of windows path. (#2)

### 0.1.1

released:

  30.11.2021

- Improvement: Provides API

- Improvement: Restructured code

### 0.1.0

released:

  26.11.2021

- Improvement: Provides `data-viewer` directive

- Improvement: Options added: file, title, data, expand