{"id":16466442,"url":"https://github.com/lukasturcani/moldoc","last_synced_at":"2025-03-16T18:31:27.819Z","repository":{"id":57442813,"uuid":"391122879","full_name":"lukasturcani/moldoc","owner":"lukasturcani","description":"Make better chemistry documentation!","archived":false,"fork":false,"pushed_at":"2024-11-20T13:40:32.000Z","size":3855,"stargazers_count":14,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-27T12:08:35.074Z","etag":null,"topics":["cheminformatics","chemistry","documentation","molecules","sphinx-extension","visualization"],"latest_commit_sha":null,"homepage":"","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/lukasturcani.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-07-30T16:08:30.000Z","updated_at":"2024-11-14T11:39:57.000Z","dependencies_parsed_at":"2024-11-12T16:19:13.758Z","dependency_job_id":"539e2957-790c-4d44-ac5a-8e5f3131d450","html_url":"https://github.com/lukasturcani/moldoc","commit_stats":{"total_commits":34,"total_committers":1,"mean_commits":34.0,"dds":0.0,"last_synced_commit":"3f654a11d67a6c08ae58d366e3d4dacf8ffb78fb"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukasturcani%2Fmoldoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukasturcani%2Fmoldoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukasturcani%2Fmoldoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukasturcani%2Fmoldoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lukasturcani","download_url":"https://codeload.github.com/lukasturcani/moldoc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243826788,"owners_count":20354220,"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":["cheminformatics","chemistry","documentation","molecules","sphinx-extension","visualization"],"created_at":"2024-10-11T11:43:46.221Z","updated_at":"2025-03-16T18:31:27.029Z","avatar_url":"https://github.com/lukasturcani.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":":author: Lukas Turcani\n\nIntroduction\n============\n\n``moldoc`` is a Sphinx extension for making better chemistry\ndocumentation. It allows you to embed 3D, interactive models of\nmolecules directly into your compiled docs. You can see it being used\nin the stk__ docs.\n\n.. image:: moldoc.gif\n\n.. __: https://stk.readthedocs.io/en/stable/basic_examples.html\n\n\nInstallation\n============\n\nFirst, run\n\n.. code-block:: bash\n\n    pip install moldoc\n\n\nand then add it to your extensions in ``conf.py``\n\n.. code-block:: python\n\n    extensions = [\n        'moldoc',\n    ]\n\n\n\nAdding Molecules into Your Docs\n===============================\n\nYou can define molecules you show with the ``moldoc`` directive,\nwhich you  can place it into your ``rst`` files\n\n.. code-block:: rst\n\n\n    .. moldoc::\n\n        # The content of a moldoc directive is just a Python script\n        # which needs to define a moldoc_display_molecule variable.\n\n        import moldoc.molecule as molecule\n\n        moldoc_display_molecule = molecule.Molecule(\n            atoms=(\n                # molecule.Atom(atomic_number, position)\n                molecule.Atom(6, (-0.06, -0.17, 0.)),\n                molecule.Atom(17, (-1.35, 1.04, -0.04)),\n                molecule.Atom(35, (1.65, 0.73, -0.06)),\n                molecule.Atom(1, (-0.15, -0.88, -0.87)),\n                molecule.Atom(1, (-0.09, -0.72, 0.97)),\n            ),\n            bonds=(\n                # molecule.Bond(atom1_id, atom2_id, order)\n                molecule.Bond(0, 1, 1),\n                molecule.Bond(0, 2, 1),\n                molecule.Bond(0, 3, 1),\n                molecule.Bond(0, 4, 1),\n            ),\n        )\n\nor in your Python docstrings\n\n.. code-block:: python\n\n    def some_fn():\n        \"\"\"\n        Do something.\n\n        .. moldoc::\n\n            # The content of a moldoc directive is just a Python script\n            # which needs to define a moldoc_display_molecule variable.\n\n            import moldoc.molecule as molecule\n\n            moldoc_display_molecule = molecule.Molecule(\n                atoms=(\n                    # molecule.Atom(atomic_number, position)\n                    molecule.Atom(6, (-0.06, -0.17, 0.)),\n                    molecule.Atom(17, (-1.35, 1.04, -0.04)),\n                    molecule.Atom(35, (1.65, 0.73, -0.06)),\n                    molecule.Atom(1, (-0.15, -0.88, -0.87)),\n                    molecule.Atom(1, (-0.09, -0.72, 0.97)),\n                ),\n                bonds=(\n                    # molecule.Bond(atom1_id, atom2_id, order)\n                    molecule.Bond(0, 1, 1),\n                    molecule.Bond(0, 2, 1),\n                    molecule.Bond(0, 3, 1),\n                    molecule.Bond(0, 4, 1),\n                ),\n            )\n\n        \"\"\"\n\n        print('In some_fn()')\n\nNote that the content in the ``moldoc`` directive is a just a Python\nscript, which has to define a ``moldoc_display_molecule`` variable\nholding a ``moldoc.molecule.Molecule`` instance.\n\nBecause the content of a ``moldoc`` directive is just a Python script\nyou can define your molecules programatically\n\n.. code-block:: python\n\n    def some_fn():\n        \"\"\"\n        Do something.\n\n        .. moldoc::\n\n            # The content of a moldoc directive is just a Python script\n            # which needs to define a moldoc_display_molecule variable.\n\n            import moldoc.molecule as molecule\n\n            atoms = [molecule.Atom(6, (i, 0., 0.)) for i in range(10)]\n            bonds = [molecule.Bond(i-1, i, 1) for i in range(1, 10)]\n\n            moldoc_display_molecule = molecule.Molecule(\n                atoms=atoms,\n                bonds=bonds,\n            )\n\n        \"\"\"\n\n        print('In some_fn()')\n\n\nConfiguration\n=============\n\nGlobal\n------\n\nYou can use the ``moldoc_default_molecule_config`` to set the default\n``MoleculeConfig`` value for all renderings. This is defined in ``conf.py``:\n\n.. code-block:: python\n\n  import moldoc.molecule as molecule\n  moldoc_default_molecule_config = molecule.MoleculeConfig(\n      background_color=molecule.Color(32, 32, 32),\n  )\n\nLocal\n-----\n\nThe display of molecules is pretty configurable, here is a snapshot of\nthe different configuration options you have, but note that this is\nnot an exhaustive list\n\n.. image:: configuration.jpg\n\nConfiguration happens on both the molecule and the atom level. For\nexample\n\n.. code-block:: rst\n\n    .. moldoc::\n\n        # The content of a moldoc directive is just a Python script\n        # which needs to define a moldoc_display_molecule variable.\n\n        import moldoc.molecule as molecule\n\n        atoms = [\n            molecule.Atom(\n                atomic_number=6,\n                position=(i, 0., 0.),\n                # Configure the atom size and color.\n                config=molecule.AtomConfig(\n                    color=molecule.Color(\n                        red=255,\n                        green=0,\n                        blue=0,\n                    ),\n                    size=1.2,\n                ),\n            ) for i in range(10),\n        ]\n        bonds = [molecule.Bond(i-1, i, 1) for i in range(1, 10)]\n\n        moldoc_display_molecule = molecule.Molecule(\n            atoms=atoms,\n            bonds=bonds,\n            config=molecule.MoleculeConfig(\n                atom_scale=1,\n                material=molecule.MeshStandardMaterial(),\n                background_color=molecule.Color(0, 255, 0),\n                is_outlined=False,\n            ),\n        )\n\n\nNote that there are many materials to choose from, and that each has\nits own set of configuration options. You can see the materials and\ntheir configuration options in ``src/moldoc/molecule.py``. Note that\nthe materials correspond to classes in ``THREE.js``, for example\nhttps://threejs.org/docs/#api/en/materials/MeshStandardMaterial, so\nif you wish to understand the configuration options of each material\nthe ``THREE.js`` docs are the place to look. Most should be\nstraighforward to understand from the name however.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukasturcani%2Fmoldoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flukasturcani%2Fmoldoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukasturcani%2Fmoldoc/lists"}