Name | moldoc JSON |
Version | 3.0.0 JSON |
download | |
home_page | |
Summary | |
upload_time | 2023-06-28 13:56:48 |
maintainer | |
docs_url | None |
author | |
requires_python | >=3.10 |
license | |
keywords | |
VCS | |
bugtrack_url | |
requirements | No requirements were recorded. |
Travis-CI | No Travis. |
coveralls test coverage | No coveralls. |
:author: Lukas Turcani Introduction ============ ``moldoc`` is a Sphinx extension for making better chemistry documentation. It allows you to embed 3D, interactive models of molecules directly into your compiled docs. You can see it being used in the stk__ docs. .. image:: moldoc.gif .. __: https://stk.readthedocs.io/en/stable/basic_examples.html Installation ============ First, run .. code-block:: bash pip install moldoc and then add it to your extensions in ``conf.py`` .. code-block:: python extensions = [ 'moldoc', ] Adding Molecules into Your Docs =============================== You can define molecules you show with the ``moldoc`` directive, which you can place it into your ``rst`` files .. code-block:: rst .. moldoc:: # The content of a moldoc directive is just a Python script # which needs to define a moldoc_display_molecule variable. import moldoc.molecule as molecule moldoc_display_molecule = molecule.Molecule( atoms=( # molecule.Atom(atomic_number, position) molecule.Atom(6, (-0.06, -0.17, 0.)), molecule.Atom(17, (-1.35, 1.04, -0.04)), molecule.Atom(35, (1.65, 0.73, -0.06)), molecule.Atom(1, (-0.15, -0.88, -0.87)), molecule.Atom(1, (-0.09, -0.72, 0.97)), ), bonds=( # molecule.Bond(atom1_id, atom2_id, order) molecule.Bond(0, 1, 1), molecule.Bond(0, 2, 1), molecule.Bond(0, 3, 1), molecule.Bond(0, 4, 1), ), ) or in your Python docstrings .. code-block:: python def some_fn(): """ Do something. .. moldoc:: # The content of a moldoc directive is just a Python script # which needs to define a moldoc_display_molecule variable. import moldoc.molecule as molecule moldoc_display_molecule = molecule.Molecule( atoms=( # molecule.Atom(atomic_number, position) molecule.Atom(6, (-0.06, -0.17, 0.)), molecule.Atom(17, (-1.35, 1.04, -0.04)), molecule.Atom(35, (1.65, 0.73, -0.06)), molecule.Atom(1, (-0.15, -0.88, -0.87)), molecule.Atom(1, (-0.09, -0.72, 0.97)), ), bonds=( # molecule.Bond(atom1_id, atom2_id, order) molecule.Bond(0, 1, 1), molecule.Bond(0, 2, 1), molecule.Bond(0, 3, 1), molecule.Bond(0, 4, 1), ), ) """ print('In some_fn()') Note that the content in the ``moldoc`` directive is a just a Python script, which has to define a ``moldoc_display_molecule`` variable holding a ``moldoc.molecule.Molecule`` instance. Because the content of a ``moldoc`` directive is just a Python script you can define your molecules programatically .. code-block:: python def some_fn(): """ Do something. .. moldoc:: # The content of a moldoc directive is just a Python script # which needs to define a moldoc_display_molecule variable. import moldoc.molecule as molecule atoms = [molecule.Atom(6, (i, 0., 0.)) for i in range(10)] bonds = [molecule.Bond(i-1, i, 1) for i in range(1, 10)] moldoc_display_molecule = molecule.Molecule( atoms=atoms, bonds=bonds, ) """ print('In some_fn()') Configuration ============= Global ------ You can use the ``moldoc_default_molecule_config`` to set the default ``MoleculeConfig`` value for all renderings. This is defined in ``conf.py``: .. code-block:: python import moldoc.molecule as molecule moldoc_default_molecule_config = molecule.MoleculeConfig( background_color=molecule.Color(32, 32, 32), ) Local ----- The display of molecules is pretty configurable, here is a snapshot of the different configuration options you have, but note that this is not an exhaustive list .. image:: configuration.jpg Configuration happens on both the molecule and the atom level. For example .. code-block:: rst .. moldoc:: # The content of a moldoc directive is just a Python script # which needs to define a moldoc_display_molecule variable. import moldoc.molecule as molecule atoms = [ molecule.Atom( atomic_number=6, position=(i, 0., 0.), # Configure the atom size and color. config=molecule.AtomConfig( color=molecule.Color( red=255, green=0, blue=0, ), size=1.2, ), ) for i in range(10), ] bonds = [molecule.Bond(i-1, i, 1) for i in range(1, 10)] moldoc_display_molecule = molecule.Molecule( atoms=atoms, bonds=bonds, config=molecule.MoleculeConfig( atom_scale=1, material=molecule.MeshStandardMaterial(), background_color=molecule.Color(0, 255, 0), is_outlined=False, ), ) Note that there are many materials to choose from, and that each has its own set of configuration options. You can see the materials and their configuration options in ``src/moldoc/molecule.py``. Note that the materials correspond to classes in ``THREE.js``, for example https://threejs.org/docs/#api/en/materials/MeshStandardMaterial, so if you wish to understand the configuration options of each material the ``THREE.js`` docs are the place to look. Most should be straighforward to understand from the name however.
{ "_id": null, "home_page": "", "name": "moldoc", "maintainer": "", "docs_url": null, "requires_python": ">=3.10", "maintainer_email": "Lukas Turcani <lukasturcani93@gmail.com>", "keywords": "", "author": "", "author_email": "", "download_url": "https://files.pythonhosted.org/packages/df/07/13a4f2993be1c28373daefe95d34b74e9593f3b6646f15144d90a7c26965/moldoc-3.0.0.tar.gz", "platform": null, "description": ":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", "bugtrack_url": null, "license": "", "summary": "", "version": "3.0.0", "project_urls": { "github": "https://github.com/lukasturcani/moldoc" }, "split_keywords": [], "urls": [ { "comment_text": "", "digests": { "blake2b_256": "735f4d60e6a760a13a75609367b931a2e7f74d5d936740a774d97c346b6c46c6", "md5": "447f6fe25bc191643e70f305237d98c7", "sha256": "46ec1573fc776b0cf3e204feddfd35beae20d27789cda14104431b758852135f" }, "downloads": -1, "filename": "moldoc-3.0.0-py3-none-any.whl", "has_sig": false, "md5_digest": "447f6fe25bc191643e70f305237d98c7", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=3.10", "size": 219170, "upload_time": "2023-06-28T13:56:46", "upload_time_iso_8601": "2023-06-28T13:56:46.154951Z", "url": "https://files.pythonhosted.org/packages/73/5f/4d60e6a760a13a75609367b931a2e7f74d5d936740a774d97c346b6c46c6/moldoc-3.0.0-py3-none-any.whl", "yanked": false, "yanked_reason": null }, { "comment_text": "", "digests": { "blake2b_256": "df0713a4f2993be1c28373daefe95d34b74e9593f3b6646f15144d90a7c26965", "md5": "de084b23c9572e90a21f39ab4ed1f55e", "sha256": "d51b655c78fbe58ab66381e57a34181aed8fac2e80dff15e4f707fcd6f2c143f" }, "downloads": -1, "filename": "moldoc-3.0.0.tar.gz", "has_sig": false, "md5_digest": "de084b23c9572e90a21f39ab4ed1f55e", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.10", "size": 1556157, "upload_time": "2023-06-28T13:56:48", "upload_time_iso_8601": "2023-06-28T13:56:48.414776Z", "url": "https://files.pythonhosted.org/packages/df/07/13a4f2993be1c28373daefe95d34b74e9593f3b6646f15144d90a7c26965/moldoc-3.0.0.tar.gz", "yanked": false, "yanked_reason": null } ], "upload_time": "2023-06-28 13:56:48", "github": true, "gitlab": false, "bitbucket": false, "codeberg": false, "github_user": "lukasturcani", "github_project": "moldoc", "travis_ci": false, "coveralls": false, "github_actions": true, "lcname": "moldoc" }