{"id":21351867,"url":"https://github.com/hygull/try-sphinx","last_synced_at":"2026-01-03T12:02:58.001Z","repository":{"id":50195379,"uuid":"179873650","full_name":"hygull/try-sphinx","owner":"hygull","description":"A project to create a beautiful documentation using Sphinx.","archived":false,"fork":false,"pushed_at":"2022-12-08T04:57:15.000Z","size":20,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-22T17:13:40.065Z","etag":null,"topics":["sphinx","sphinx-documentation"],"latest_commit_sha":null,"homepage":"https://hygull.github.io/try-sphinx/","language":null,"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/hygull.png","metadata":{"files":{"readme":"README.md","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":"2019-04-06T18:51:04.000Z","updated_at":"2019-04-07T07:52:30.000Z","dependencies_parsed_at":"2023-01-24T13:00:32.191Z","dependency_job_id":null,"html_url":"https://github.com/hygull/try-sphinx","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hygull%2Ftry-sphinx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hygull%2Ftry-sphinx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hygull%2Ftry-sphinx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hygull%2Ftry-sphinx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hygull","download_url":"https://codeload.github.com/hygull/try-sphinx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243826783,"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":["sphinx","sphinx-documentation"],"created_at":"2024-11-22T03:11:38.931Z","updated_at":"2026-01-03T12:02:52.971Z","avatar_url":"https://github.com/hygull.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# try-sphinx\n\nA project to create a beautiful documentation using Sphinx.\n\n### System/Language detail \n\n| Title | Resource | Description |\n| --- | --- | --- |\n| Operating system | MAC OS X| You can try it on Windows/Linux too| \n| Python version| Python3.6.7 | You can try it with Python3 only. For more details visit [https://pypi.org/project/Sphinx/](https://pypi.org/project/Sphinx/) and check the supported versions |\n\n### Quick start\n\n1. Create any directory \u0026 navigate inside that.\n\t\n\t+ `cd ~/Projects/Python3/Sphinx/`\n\n\t+ `mkdir try_sphinx`\n\n\t+ `cd try_sphinx/`\n\n\n2. Create virtual environment \u0026 activate it.\n\n\t\u003e **Note:** In windows, you can try `.\\venv3.6.7\\Scripts\\activate`.\n\n\t+ `python3 -m virtaulenv venv3.6.7`\n\t\n\t+ `source venv3.6.7/bin/activate`\n\n3. Install **sphinx**.\n\n\t+ `pip install sphinx`\n\n\n\t\u003e You can have a look at [pip install history for sphinx on MAC OS X](./files/sphinx-install-history.md) of full install history of **sphinx**.\n\n```bash\n(venv3.6.7)Rishikeshs-Air:try_sphinx hygull$ pip install sphinx\nYou are using pip version 6.0.8, however version 19.0.3 is available.\nYou should consider upgrading via the 'pip install --upgrade pip' command.\nCollecting sphinx\n  Downloading https://files.pythonhosted.org/packages/17/a4/338f9cbc334dd27c972ea9aae3e054068c9b3a642c8abb1f67f93a59a85e/Sphinx-2.0.0-py2.py3-none-any.whl (3.2MB)\n    100% |################################| 3.2MB 111kB/s \nCollecting docutils\u003e=0.12 (from sphinx)\n...\n\n```\n\n4. Create a directory named **docs** and navigate inside that.\n\n\t+ `mkdir docs`\n\n\t+ `cd docs`\n\n5. In here, run the below command. You can see output [here](./files/sphinx-quickstart-output.md) if you wish to see how it appeared in my case.\n\n\t+ `sphinx-quickstart`\n\n\n6. Finally, run the below 2 commands one after one\n\n\t\u003e **Note:** In Windows, you can try **start source\\html\\index.html** to open the index.html file in your browser. \n\t\u003e\n\t\u003eAnyways, you can open the directory using Explorer/Finder etc. \tand click/dbclick (based on settings) to open it and see the page in your browser.\n\t\u003e \n\t\u003eIn my case, I am on MAC OS X. \n\n\t+ `make html`\n\n\t+ `open source/html/index.html`\n\nNow, you can see a beauiful HTML page generated for you. Now you can have a look at [template](https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/#id1) or [reSturctureText](http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) and start implementing/writing the documentation you want.\n\n### Extra steps\n\n7. Install recommonmark (for markdown support)\n\n\t+ `pip install recommonmark`\n\n8. Add recommonmark to list\n\n\t+ Just open the docs/source/conf.py\n\n\t+ Replace `extensions = []` with `extensions = ['recommonmark']`\n\n\n\n### Quick overview of my terminal\n\n```bash\nRishikeshs-Air:~ hygull$ cd ~/Projects/Python3/Sphinx/\nRishikeshs-Air:Sphinx hygull$ \nRishikeshs-Air:Sphinx hygull$ mv try_sphinx/ try_sphinx2\nRishikeshs-Air:Sphinx hygull$ \nRishikeshs-Air:Sphinx hygull$ mkdir try_sphinx\nRishikeshs-Air:Sphinx hygull$ \nRishikeshs-Air:Sphinx hygull$ cd try_sphinx\nRishikeshs-Air:try_sphinx hygull$ \n```\n\n```bash\nRishikeshs-Air:try_sphinx hygull$ python3 -m virtualenv venv3.6.7\nUsing base prefix '/Library/Frameworks/Python.framework/Versions/3.6'\nNew python executable in /Users/hygull/Projects/Python3/Sphinx/try_sphinx/venv3.6.7/bin/python3\nAlso creating executable in /Users/hygull/Projects/Python3/Sphinx/try_sphinx/venv3.6.7/bin/python\nInstalling setuptools, pip, wheel...\ndone.\nRishikeshs-Air:try_sphinx hygull$\n```\n\n```bash\nRishikeshs-Air:try_sphinx hygull$ source ./venv3.6.7/bin/activate\n(venv3.6.7) Rishikeshs-Air:try_sphinx hygull$ \n```\n\n```bash\n(venv3.6.7)Rishikeshs-Air:try_sphinx hygull$ pip install sphinx\nCollecting sphinx\n  Using cached https://files.pythonhosted.org/packages/17/a4/338f9cbc334dd27c972ea9aae3e054068c9b3a642c8abb1f67f93a59a85e/Sphinx-2.0.0-py2.py3-none-any.whl\n...\n```\n\n\n```bash\n(venv3.6.7) Rishikeshs-Air:try_sphinx hygull$ mkdir docs\n```\n\n```bash\n(venv3.6.7) Rishikeshs-Air:try_sphinx hygull$ cd docs/\n```\n\n```bash\n(venv3.6.7) Rishikeshs-Air:docs hygull$ make html\nRunning Sphinx v2.0.0\nmaking output directory... done\nbuilding [mo]: targets for 0 po files that are out of date\nbuilding [html]: targets for 1 source files that are out of date\nupdating environment: 1 added, 0 changed, 0 removed\nreading sources... [100%] index                                                          \nlooking for now-outdated files... none found\npickling environment... done\nchecking consistency... done\npreparing documents... done\nwriting output... [100%] index                                                           \ngenerating indices... genindex\nwriting additional pages... search\ncopying static files... done\ncopying extra files... done\ndumping search index in English (code: en) ... done\ndumping object inventory... done\nbuild succeeded.\n\nThe HTML pages are in build/html.\n```\n\n\n```bash\n(venv3.6.7) Rishikeshs-Air:docs hygull$ open build/html/index.html \n(venv3.6.7) Rishikeshs-Air:docs hygull$ \n```\n\n```bash\n(venv3.6.7) Rishikeshs-MacBook-Air:try_sphinx hygull$ pip install recommonmark\nCollecting recommonmark\n  Downloading https://files.pythonhosted.org/packages/9b/3d/92ea48401622510e57b4bdaa74dc9db2fb9e9e892324b48f9c02d716a93a/recommonmark-0.5.0-py2.py3-none-any.whl\nRequirement already satisfied: docutils\u003e=0.11 in ./venv3.6.7/lib/python3.6/site-packages (from recommonmark) (0.14)\nRequ...\n...\n\n```\n\n\n\n### References\n\n- [x] [Getting Started with Sphinx](https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html)\n\n- [x] [Video guide](https://youtu.be/oJsUvBQyHBs)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhygull%2Ftry-sphinx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhygull%2Ftry-sphinx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhygull%2Ftry-sphinx/lists"}