From e3aaf6309e65ad8d814d9713a20d4e930b07cbe9 Mon Sep 17 00:00:00 2001 From: Arijit De Date: Wed, 31 May 2023 20:50:06 +0530 Subject: [PATCH 1/5] Publish PDF version of RTD documentation Made changes in the .readthedocs.yaml to enable format for downloading pdf and epub versions of the documentation and added latex_elements in the conf.py file which generates the pdf without blank pages. The minimum version requirement for sphinx was 6.2.1 which was causing build failure in read the docs, hence changing it 3.3.1 as written in setup.cfg of nexB/aboutcode Signed-off-by: Arijit De --- .readthedocs.yml | 5 +++++ docs/source/conf.py | 6 ++++++ setup.cfg | 2 +- 3 files changed, 12 insertions(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 1b71cd9e..2a7dc0b4 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -5,6 +5,11 @@ # Required version: 2 +# Build PDF & ePub +formats: + - epub + - pdf + # Where the Sphinx conf.py file is located sphinx: configuration: docs/source/conf.py diff --git a/docs/source/conf.py b/docs/source/conf.py index d5435e75..39835c69 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -95,3 +95,9 @@ .. role:: img-title-para """ + +# -- Options for LaTeX output ------------------------------------------------- + +latex_elements = { + 'classoptions': ',openany,oneside' +} \ No newline at end of file diff --git a/setup.cfg b/setup.cfg index 18bfbdec..b02fd346 100644 --- a/setup.cfg +++ b/setup.cfg @@ -58,6 +58,6 @@ testing = isort docs = - Sphinx == 6.2.1 + Sphinx == 5.1.0 sphinx-rtd-theme >= 0.5.0 doc8 >= 0.8.1 From 5be7a24d3f6b581f3dd9aef193923a4a23420dea Mon Sep 17 00:00:00 2001 From: Ayan Sinha Mahapatra Date: Tue, 6 Jun 2023 21:46:49 +0530 Subject: [PATCH 2/5] Bump github actions versions #75 Update the following actions: * actions/checkout * actions/setup-python Reference: https://github.com/nexB/skeleton/issues/75 Signed-off-by: Ayan Sinha Mahapatra --- .github/workflows/docs-ci.yml | 4 ++-- .github/workflows/pypi-release.yml | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docs-ci.yml b/.github/workflows/docs-ci.yml index 18a44aa0..511b7c28 100644 --- a/.github/workflows/docs-ci.yml +++ b/.github/workflows/docs-ci.yml @@ -13,10 +13,10 @@ jobs: steps: - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v2 + uses: actions/setup-python@v4 with: python-version: ${{ matrix.python-version }} diff --git a/.github/workflows/pypi-release.yml b/.github/workflows/pypi-release.yml index 22315ff0..4ebe10d1 100644 --- a/.github/workflows/pypi-release.yml +++ b/.github/workflows/pypi-release.yml @@ -24,9 +24,9 @@ jobs: runs-on: ubuntu-20.04 steps: - - uses: actions/checkout@master + - uses: actions/checkout@v3 - name: Set up Python - uses: actions/setup-python@v1 + uses: actions/setup-python@v4 with: python-version: 3.9 From f16eea2d0e7f15567aceeed4cd129489fdf529f5 Mon Sep 17 00:00:00 2001 From: Ayan Sinha Mahapatra Date: Fri, 7 Jul 2023 21:00:31 +0530 Subject: [PATCH 3/5] Generate RTD from README * Remove skeleton docs * Use the minimal README in the RTD build Signed-off-by: Ayan Sinha Mahapatra --- docs/source/contribute/contrib_doc.rst | 314 ------------------------- docs/source/index.rst | 9 +- docs/source/skeleton-usage.rst | 160 ------------- 3 files changed, 2 insertions(+), 481 deletions(-) delete mode 100644 docs/source/contribute/contrib_doc.rst delete mode 100644 docs/source/skeleton-usage.rst diff --git a/docs/source/contribute/contrib_doc.rst b/docs/source/contribute/contrib_doc.rst deleted file mode 100644 index 13882e10..00000000 --- a/docs/source/contribute/contrib_doc.rst +++ /dev/null @@ -1,314 +0,0 @@ -.. _contrib_doc_dev: - -Contributing to the Documentation -================================= - -.. _contrib_doc_setup_local: - -Setup Local Build ------------------ - -To get started, create or identify a working directory on your local machine. - -Open that directory and execute the following command in a terminal session:: - - git clone https://github.com/nexB/skeleton.git - -That will create an ``/skeleton`` directory in your working directory. -Now you can install the dependencies in a virtualenv:: - - cd skeleton - ./configure --docs - -.. note:: - - In case of windows, run ``configure --docs`` instead of this. - -Now, this will install the following prerequisites: - -- Sphinx -- sphinx_rtd_theme (the format theme used by ReadTheDocs) -- docs8 (style linter) - -These requirements are already present in setup.cfg and `./configure --docs` installs them. - -Now you can build the HTML documents locally:: - - source venv/bin/activate - cd docs - make html - -Assuming that your Sphinx installation was successful, Sphinx should build a local instance of the -documentation .html files:: - - open build/html/index.html - -.. note:: - - In case this command did not work, for example on Ubuntu 18.04 you may get a message like “Couldn’t - get a file descriptor referring to the console”, try: - - :: - - see build/html/index.html - -You now have a local build of the AboutCode documents. - -.. _contrib_doc_share_improvements: - -Share Document Improvements ---------------------------- - -Ensure that you have the latest files:: - - git pull - git status - -Before commiting changes run Continious Integration Scripts locally to run tests. Refer -:ref:`doc_ci` for instructions on the same. - -Follow standard git procedures to upload your new and modified files. The following commands are -examples:: - - git status - git add source/index.rst - git add source/how-to-scan.rst - git status - git commit -m "New how-to document that explains how to scan" - git status - git push - git status - -The Scancode-Toolkit webhook with ReadTheDocs should rebuild the documentation after your -Pull Request is Merged. - -Refer the `Pro Git Book `_ available online for Git tutorials -covering more complex topics on Branching, Merging, Rebasing etc. - -.. _doc_ci: - -Continuous Integration ----------------------- - -The documentations are checked on every new commit through Travis-CI, so that common errors are -avoided and documentation standards are enforced. Travis-CI presently checks for these 3 aspects -of the documentation : - -1. Successful Builds (By using ``sphinx-build``) -2. No Broken Links (By Using ``link-check``) -3. Linting Errors (By Using ``Doc8``) - -So run these scripts at your local system before creating a Pull Request:: - - cd docs - ./scripts/sphinx_build_link_check.sh - ./scripts/doc8_style_check.sh - -If you don't have permission to run the scripts, run:: - - chmod u+x ./scripts/doc8_style_check.sh - -.. _doc_style_docs8: - -Style Checks Using ``Doc8`` ---------------------------- - -How To Run Style Tests -^^^^^^^^^^^^^^^^^^^^^^ - -In the project root, run the following commands:: - - $ cd docs - $ ./scripts/doc8_style_check.sh - -A sample output is:: - - Scanning... - Validating... - docs/source/misc/licence_policy_plugin.rst:37: D002 Trailing whitespace - docs/source/misc/faq.rst:45: D003 Tabulation used for indentation - docs/source/misc/faq.rst:9: D001 Line too long - docs/source/misc/support.rst:6: D005 No newline at end of file - ======== - Total files scanned = 34 - Total files ignored = 0 - Total accumulated errors = 326 - Detailed error counts: - - CheckCarriageReturn = 0 - - CheckIndentationNoTab = 75 - - CheckMaxLineLength = 190 - - CheckNewlineEndOfFile = 13 - - CheckTrailingWhitespace = 47 - - CheckValidity = 1 - -Now fix the errors and run again till there isn't any style error in the documentation. - -What is Checked? -^^^^^^^^^^^^^^^^ - -PyCQA is an Organization for code quality tools (and plugins) for the Python programming language. -Doc8 is a sub-project of the same Organization. Refer this `README `_ for more details. - -What is checked: - - - invalid rst format - D000 - - lines should not be longer than 100 characters - D001 - - - RST exception: line with no whitespace except in the beginning - - RST exception: lines with http or https URLs - - RST exception: literal blocks - - RST exception: rst target directives - - - no trailing whitespace - D002 - - no tabulation for indentation - D003 - - no carriage returns (use UNIX newlines) - D004 - - no newline at end of file - D005 - -.. _doc_interspinx: - -Interspinx ----------- - -ScanCode toolkit documentation uses `Intersphinx `_ -to link to other Sphinx Documentations, to maintain links to other Aboutcode Projects. - -To link sections in the same documentation, standart reST labels are used. Refer -`Cross-Referencing `_ for more information. - -For example:: - - .. _my-reference-label: - - Section to cross-reference - -------------------------- - - This is the text of the section. - - It refers to the section itself, see :ref:`my-reference-label`. - -Now, using Intersphinx, you can create these labels in one Sphinx Documentation and then referance -these labels from another Sphinx Documentation, hosted in different locations. - -You just have to add the following in the ``conf.py`` file for your Sphinx Documentation, where you -want to add the links:: - - extensions = [ - 'sphinx.ext.intersphinx' - ] - - intersphinx_mapping = {'aboutcode': ('https://aboutcode.readthedocs.io/en/latest/', None)} - -To show all Intersphinx links and their targets of an Intersphinx mapping file, run:: - - python -msphinx.ext.intersphinx https://aboutcode.readthedocs.io/en/latest/objects.inv - -.. WARNING:: - - ``python -msphinx.ext.intersphinx https://aboutcode.readthedocs.io/objects.inv`` will give - error. - -This enables you to create links to the ``aboutcode`` Documentation in your own Documentation, -where you modified the configuration file. Links can be added like this:: - - For more details refer :ref:`aboutcode:doc_style_guide`. - -You can also not use the ``aboutcode`` label assigned to all links from aboutcode.readthedocs.io, -if you don't have a label having the same name in your Sphinx Documentation. Example:: - - For more details refer :ref:`doc_style_guide`. - -If you have a label in your documentation which is also present in the documentation linked by -Intersphinx, and you link to that label, it will create a link to the local label. - -For more information, refer this tutorial named -`Using Intersphinx `_. - -.. _doc_style_conv: - -Style Conventions for the Documentaion --------------------------------------- - -1. Headings - - (`Refer `_) - Normally, there are no heading levels assigned to certain characters as the structure is - determined from the succession of headings. However, this convention is used in Python’s Style - Guide for documenting which you may follow: - - # with overline, for parts - - * with overline, for chapters - - =, for sections - - -, for subsections - - ^, for sub-subsections - - ", for paragraphs - -2. Heading Underlines - - Do not use underlines that are longer/shorter than the title headline itself. As in: - - :: - - Correct : - - Extra Style Checks - ------------------ - - Incorrect : - - Extra Style Checks - ------------------------ - -.. note:: - - Underlines shorter than the Title text generates Errors on sphinx-build. - - -3. Internal Links - - Using ``:ref:`` is advised over standard reStructuredText links to sections (like - ```Section title`_``) because it works across files, when section headings are changed, will - raise warnings if incorrect, and works for all builders that support cross-references. - However, external links are created by using the standard ```Section title`_`` method. - -4. Eliminate Redundancy - - If a section/file has to be repeated somewhere else, do not write the exact same section/file - twice. Use ``.. include: ../README.rst`` instead. Here, ``../`` refers to the documentation - root, so file location can be used accordingly. This enables us to link documents from other - upstream folders. - -5. Using ``:ref:`` only when necessary - - Use ``:ref:`` to create internal links only when needed, i.e. it is referenced somewhere. - Do not create references for all the sections and then only reference some of them, because - this created unnecessary references. This also generates ERROR in ``restructuredtext-lint``. - -6. Spelling - - You should check for spelling errors before you push changes. `Aspell `_ - is a GNU project Command Line tool you can use for this purpose. Download and install Aspell, - then execute ``aspell check `` for all the files changed. Be careful about not - changing commands or other stuff as Aspell gives prompts for a lot of them. Also delete the - temporary ``.bak`` files generated. Refer the `manual `_ for more - information on how to use. - -7. Notes and Warning Snippets - - Every ``Note`` and ``Warning`` sections are to be kept in ``rst_snippets/note_snippets/`` and - ``rst_snippets/warning_snippets/`` and then included to eliminate redundancy, as these are - frequently used in multiple files. - -Converting from Markdown ------------------------- - -If you want to convert a ``.md`` file to a ``.rst`` file, this `tool `_ -does it pretty well. You'd still have to clean up and check for errors as this contains a lot of -bugs. But this is definitely better than converting everything by yourself. - -This will be helpful in converting GitHub wiki's (Markdown Files) to reStructuredtext files for -Sphinx/ReadTheDocs hosting. diff --git a/docs/source/index.rst b/docs/source/index.rst index eb63717b..687969ea 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,12 +1,7 @@ -Welcome to nexb-skeleton's documentation! +Welcome to PURLdb documentation! ========================================= -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - skeleton-usage - contribute/contrib_doc +.. include:: ../../README.rst Indices and tables ================== diff --git a/docs/source/skeleton-usage.rst b/docs/source/skeleton-usage.rst deleted file mode 100644 index cde23dcd..00000000 --- a/docs/source/skeleton-usage.rst +++ /dev/null @@ -1,160 +0,0 @@ -Usage -===== -A brand new project -------------------- -.. code-block:: bash - - git init my-new-repo - cd my-new-repo - git pull git@github.com:nexB/skeleton - - # Create the new repo on GitHub, then update your remote - git remote set-url origin git@github.com:nexB/your-new-repo.git - -From here, you can make the appropriate changes to the files for your specific project. - -Update an existing project ---------------------------- -.. code-block:: bash - - cd my-existing-project - git remote add skeleton git@github.com:nexB/skeleton - git fetch skeleton - git merge skeleton/main --allow-unrelated-histories - -This is also the workflow to use when updating the skeleton files in any given repository. - -Customizing ------------ - -You typically want to perform these customizations: - -- remove or update the src/README.rst and tests/README.rst files -- set project info and dependencies in setup.cfg -- check the configure and configure.bat defaults - -Initializing a project ----------------------- - -All projects using the skeleton will be expected to pull all of it dependencies -from thirdparty.aboutcode.org/pypi or the local thirdparty directory, using -requirements.txt and/or requirements-dev.txt to determine what version of a -package to collect. By default, PyPI will not be used to find and collect -packages from. - -In the case where we are starting a new project where we do not have -requirements.txt and requirements-dev.txt and whose dependencies are not yet on -thirdparty.aboutcode.org/pypi, we run the following command after adding and -customizing the skeleton files to your project: - -.. code-block:: bash - - ./configure - -This will initialize the virtual environment for the project, pull in the -dependencies from PyPI and add them to the virtual environment. - - -Generating requirements.txt and requirements-dev.txt ----------------------------------------------------- - -After the project has been initialized, we can generate the requirements.txt and -requirements-dev.txt files. - -Ensure the virtual environment is enabled. - -.. code-block:: bash - - source venv/bin/activate - -To generate requirements.txt: - -.. code-block:: bash - - python etc/scripts/gen_requirements.py -s venv/lib/python/site-packages/ - -Replace \ with the version number of the Python being used, for example: -``venv/lib/python3.6/site-packages/`` - -To generate requirements-dev.txt after requirements.txt has been generated: - -.. code-block:: bash - - ./configure --dev - python etc/scripts/gen_requirements_dev.py -s venv/lib/python/site-packages/ - -Note: on Windows, the ``site-packages`` directory is located at ``venv\Lib\site-packages\`` - -.. code-block:: bash - - python .\\etc\\scripts\\gen_requirements.py -s .\\venv\\Lib\\site-packages\\ - .\configure --dev - python .\\etc\\scripts\\gen_requirements_dev.py -s .\\venv\\Lib\\site-packages\\ - - -Collecting and generating ABOUT files for dependencies ------------------------------------------------------- - -Ensure that the dependencies used by ``etc/scripts/fetch_thirdparty.py`` are installed: - -.. code-block:: bash - - pip install -r etc/scripts/requirements.txt - -Once we have requirements.txt and requirements-dev.txt, we can fetch the project -dependencies as wheels and generate ABOUT files for them: - -.. code-block:: bash - - python etc/scripts/fetch_thirdparty.py -r requirements.txt -r requirements-dev.txt - -There may be issues with the generated ABOUT files, which will have to be -corrected. You can check to see if your corrections are valid by running: - -.. code-block:: bash - - python etc/scripts/check_thirdparty.py -d thirdparty - -Once the wheels are collected and the ABOUT files are generated and correct, -upload them to thirdparty.aboutcode.org/pypi by placing the wheels and ABOUT -files from the thirdparty directory to the pypi directory at -https://github.com/nexB/thirdparty-packages - - -Usage after project initialization ----------------------------------- - -Once the ``requirements.txt`` and ``requirements-dev.txt`` have been generated -and the project dependencies and their ABOUT files have been uploaded to -thirdparty.aboutcode.org/pypi, you can configure the project as needed, typically -when you update dependencies or use a new checkout. - -If the virtual env for the project becomes polluted, or you would like to remove -it, use the ``--clean`` option: - -.. code-block:: bash - - ./configure --clean - -Then you can run ``./configure`` again to set up the project virtual environment. - -To set up the project for development use: - -.. code-block:: bash - - ./configure --dev - -To update the project dependencies (adding, removing, updating packages, etc.), -update the dependencies in ``setup.cfg``, then run: - -.. code-block:: bash - - ./configure --clean # Remove existing virtual environment - source venv/bin/activate # Ensure virtual environment is activated - python etc/scripts/gen_requirements.py -s venv/lib/python/site-packages/ # Regenerate requirements.txt - python etc/scripts/gen_requirements_dev.py -s venv/lib/python/site-packages/ # Regenerate requirements-dev.txt - pip install -r etc/scripts/requirements.txt # Install dependencies needed by etc/scripts/bootstrap.py - python etc/scripts/fetch_thirdparty.py -r requirements.txt -r requirements-dev.txt # Collect dependency wheels and their ABOUT files - -Ensure that the generated ABOUT files are valid, then take the dependency wheels -and ABOUT files and upload them to thirdparty.aboutcode.org/pypi. From adb305d57503ddd5aab7ba1307166a61e0a0077d Mon Sep 17 00:00:00 2001 From: Ayan Sinha Mahapatra Date: Fri, 7 Jul 2023 21:44:21 +0530 Subject: [PATCH 4/5] Fix unordered lists and misc Reference: readthedocs/sphinx_rtd_theme#1115 Signed-off-by: Ayan Sinha Mahapatra --- .readthedocs.yml | 5 +++++ docs/source/index.rst | 2 +- setup.cfg | 6 +++--- 3 files changed, 9 insertions(+), 4 deletions(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 2a7dc0b4..97ffa418 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -5,6 +5,11 @@ # Required version: 2 +build: + os: ubuntu-22.04 + tools: + python: "3.11" + # Build PDF & ePub formats: - epub diff --git a/docs/source/index.rst b/docs/source/index.rst index 687969ea..b9dfad4d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,4 +1,4 @@ -Welcome to PURLdb documentation! +Welcome to PurlDB documentation! ========================================= .. include:: ../../README.rst diff --git a/setup.cfg b/setup.cfg index a6e78830..12485874 100644 --- a/setup.cfg +++ b/setup.cfg @@ -73,6 +73,6 @@ testing = mock docs = - Sphinx == 5.1.0 - sphinx-rtd-theme >= 0.5.0 - doc8 >= 0.8.1 + Sphinx==5.0.2 + sphinx-rtd-theme==1.0.0 + doc8==0.11.2 \ No newline at end of file From 51fbb81aec3689b4de3dcd0870d51deeda358f98 Mon Sep 17 00:00:00 2001 From: Ayan Sinha Mahapatra Date: Mon, 10 Jul 2023 20:33:31 +0530 Subject: [PATCH 5/5] Set correct doc edit link Signed-off-by: Ayan Sinha Mahapatra --- docs/source/conf.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 39835c69..abad1f97 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -17,7 +17,7 @@ # -- Project information ----------------------------------------------------- -project = "nexb-skeleton" +project = "PurlDB" copyright = "nexB Inc. and others." author = "AboutCode.org authors and contributors" @@ -67,8 +67,8 @@ html_context = { "display_github": True, "github_user": "nexB", - "github_repo": "nexb-skeleton", - "github_version": "develop", # branch + "github_repo": "purldb", + "github_version": "main", # branch "conf_py_path": "/docs/source/", # path in the checkout to the docs root }