{"id":19136927,"url":"https://github.com/apptainer/singularity-userdocs","last_synced_at":"2025-05-06T20:11:18.958Z","repository":{"id":43397088,"uuid":"135755542","full_name":"apptainer/singularity-userdocs","owner":"apptainer","description":"User Documentation","archived":false,"fork":false,"pushed_at":"2022-03-03T16:44:37.000Z","size":183111,"stargazers_count":21,"open_issues_count":19,"forks_count":56,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-19T14:57:38.166Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apptainer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"contributing.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"security.rst","support":null}},"created_at":"2018-06-01T19:24:09.000Z","updated_at":"2024-12-30T21:16:14.000Z","dependencies_parsed_at":"2022-09-23T09:43:19.318Z","dependency_job_id":null,"html_url":"https://github.com/apptainer/singularity-userdocs","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apptainer%2Fsingularity-userdocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apptainer%2Fsingularity-userdocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apptainer%2Fsingularity-userdocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apptainer%2Fsingularity-userdocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apptainer","download_url":"https://codeload.github.com/apptainer/singularity-userdocs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252761228,"owners_count":21800125,"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":[],"created_at":"2024-11-09T06:35:54.300Z","updated_at":"2025-05-06T20:11:18.895Z","avatar_url":"https://github.com/apptainer.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Singularity User Docs\n\nIMPORTANT NOTE: Singularity has been renamed to\n[Apptainer](https://apptainer.org/news/community-announcement-20211130).\nThis repository is now only for archiving the history.\nSubmit all current issues and pull requests to\n[https://github.com/apptainer/apptainer](https://github.com/apptainer/apptainer).\n\n## Setting up an environment to contribute\n\nThe Singularity user documentation is written in [reStructured Text (RST)\nformat](http://docutils.sourceforge.net/rst.html) and generated using\n[Sphinx](https://pypi.org/project/Sphinx/). The\n[ReadTheDocs](https://readthedocs.org/) theme for Sphinx is used.\n\nWe use RST instead of markdown as it's better at handling large documents with\nmany linked sections, and Sphinx makes it easy to produce online documentation\nas well as PDFs.\n\nSphinx is written in Python. To get setup to contribute:\n\n- Install Python 3.5 or newer, from your OS package manager or the [Python download\n  site](https://www.python.org/downloads/)\n- Use `pip3`to install Sphinx and the RTD theme package into your home directory:\n\n```sh\npip3 install --user Sphinx sphinx-rtd-theme\n```\n\nIf your version of python 3 does not come with `pip` / `pip3`, you may need to\ninstall a `python3-pip`package with `apt` or `yum`, or you can install pip\nfollowing [the instructions here](https://pip.pypa.io/en/stable/installing/).\n\nYou're all set! After this you will only need to use your favorite editor to\nwork with the RST files.\n\n## How to edit \u0026 write RST\n\nA Sphinx documentation project has some structure that it's good to know before\nyou dive in and start editing or writing content.\n\n### Structure of the project\n\nThis project maintains the following structure:\n\n1. `index.rst` : contains the front page of the online documentation and the\n   initial table of contents tree. Every documentation section is referenced by\n   a tag next to its name. (e.g. ``Quick Start \u003cquick_start\u003e``)\n2. All other `.rst`files are sections named to match reference tags described\n   before. So, for the `\u003cquick_start\u003e` reference in `index.rst` you'll find\n   a `quick_start.rst` file with the content for that section.\n3. The configuration used to build the final documentations from the `.rst`\n   files is set in the `conf.py` file.\n\n### The conf.py file\n\nThis file sets the themes, extensions, variables and naming scheme for output\ncreated when building the documentation with Sphinx. Some important elements\ninclude:\n\n- `version` : Describes the current version of `Singularity` that the\n  documentation is for. We set version to the `major.minor` values, e.g. `3.5`,\n  as we are not creating separate documentation for each patch release.\n- `release`: Would be used to specify the current release of the software being\n  documented, including patch number, alpha tags etc. We leave this the same as\n  `version` as we only generate documentation for each `major.minor` version of\n  singularity.\n- `html_theme`: Sets the theme to be used for HTML output. We are using the RTD\n  or Read The Docs theme.\n- `html_context`: Options here control links back to our GitHub repository.\n- `html_logo`: The logo for the sidebar\n- `html_favicon`: The `favicon`for the entire project\n\n### Cheatsheet to get started with reStructured (RST) Text\n\nRST is similar to Markdown, but has enough differences that you are likely to be\ncaught out a few times until you are familiar with it. Let's look at some of the\ncommon things you need to do when writing or editing RST.\n\n#### 1. Create a section/subsection/subsubsection title\n\nSections titles are defined by surrounding or underlining them\nwith different characters. Each combination of overline/underline and character\nused represents a different level section.\n\n- To create a main section title: A main section title is surrounded (above and\n  below) with `=` characters:\n\n```rst\n================\nNew Main Section\n================\n```\n\n- To create a sub-section: A sub section title is surrounded (above and below)\n  with `-` characters:\n\n```rst\n---------------\nNew Sub section\n---------------\n```\n\n- To create a sub-sub-section: A sub-sub section title is underlined with ``=``\n  characters:\n\n```rst\nNew sub-sub section\n===================\n```\n\n- If you need more levels you can keep going: A sub-sub-sub-section is\n  underlined with `-` characters.\n\n```rst\nNew sub-sub-sub section\n-----------------------\n```\n\nRST doesn't actually set a specific order for the characters you use to\nunderline and overline titles, as it will pick up the method used for the first\ntitle at each level. Following the convention above, though, will make it easy\nto see what level a section is wherever you are working in the documentation.\n\n#### 2. Reference sections\n\nTo reference a section in an RST file you need to first create the reference\nabove the title you need to reference, and second to reference it where you need\nthe link to the reference section. When you build HTML or PDF output with Sphinx\nit will create the links for you, so the reader can jump around the\ndocumentation easily.\n\n##### Step 1: Create the reference\n\nTo create the reference on the section you need to link, you must specify a\ntag:\n\n```rst\n.. _build-docker:\n\n-------------------------\nBuild from a Docker Image\n-------------------------\n```\n\nThis example will let you refer to the section titled \"Build from a Docker\nImage\" with the tag `build-docker`. Note that the tag here doesn't include the\n`_` that you have to prefix it with when creating the reference.\n\n##### Step 2: Reference it\n\nTo reference a section you need to use this syntax:\n\n```rst\n:ref:`read the section covering docker images \u003cbuild-docker\u003e`\n```\n\n`:ref:` tells Sphinx that this is a reference. In between the `` ` ``you should\nprovide text for the link, and then the tag you created above between `\u003c \u003e`.\n\n### Further Reading\n\nThese are some of the basics of RST. For a more complete introduction, see the\n[Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)\n\n### Building HTML documentation\n\nTo build the HTML documentation, make sure you are in the top level of the\n`singularity-userdocs` repository and run:\n\n```sh\nmake html SKIPCLI=1\n```\n\nThis will generate a folder called `_build/html` with the output. Open\n`index.html` to browse the documentation.\n\nThe `SKIPCLI=1` option tells `make` not to generate the CLI reference, which is\ncreated automatically from the Singularity source code. You can generate the CLI\ndocumentation by running `make html` alone. This requires a Go build\nenvironment (see below).\n\n### Generating PDF files from RST\n\nThis is very similar to the previous step, you will need to run:\n\n```sh\nmake latexpdf SKIPCLI=1\n```\n\nOutput is written into `_build/latex` and the final PDF will be named\n`singularity-userdocs.pdf`\n\n### Generating EPUB from RST\n\nVery similar to the previous command, you will just need to run:\n\n```sh\nmake epub SKIPCLI=1\n```\n\nOutput is written into `_build/epub` and the final EPUB will be named\n`singularity-userdocs.epub`\n\n## Generating CLI docs\n\nThe Singularity CLI docs are generated using the actual code from Singularity.\nTo do this, we include Singularity as a git submodule, and whenever a Makefile\ntarget (like `make html`) is run, Singularity itself is compiled and used to\ngenerate the CLI docs.\n\nHowever, you might not want to compile Singularity, either because you can't on\nyour machine, or because you want to test out a quick change to the docs.  If\nthis is the case, you can skip the CLI doc generation using the `SKIPCLI`\nargument.  For example, to rebuild the HTML docs without including the CLI docs,\njust run `make html SKIPCLI=1`.\n\nIf Singularity has been updated and you want to synchronize the CLI docs with\nthe new version of Singularity, you'll have to update the submodule.  To do\nthis, just run:\n\n```bash\ngit submodule update --remote --merge\ngit add vendor/src/github.com/apptainer/singularity\ngit commit\n```\n\nThis will update the Singularity submodule to the latest version of the master\nbranch.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapptainer%2Fsingularity-userdocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapptainer%2Fsingularity-userdocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapptainer%2Fsingularity-userdocs/lists"}