diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 40bc249..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,31 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SPHINXAUTOBUILD = sphinx-autobuild -SOURCEDIR = source -BUILDDIR = _build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -docs-check: - @${ACTIVATE} sphinx-build -E -W -b html docs/source docs/_build/ - -# Run the development server using sphinx-autobuild -docs: - @echo - @echo "Starting up the docs server..." - @echo - $(SPHINXAUTOBUILD) --port 8000 --watch ${SOURCEDIR} $(SOURCEDIR) "$(BUILDDIR)/html" $(SPHINXOPTS) $(O) - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 4a3c1a4..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,47 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -if "%SPHINXAUTOBUILD%" == "" ( - set SPHINXAUTOBUILD=sphinx-autobuild -) -set SOURCEDIR=source -set BUILDDIR=build - -if "%1" == "" goto help - -if "%1" == "docs" goto docs - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:docs -@echo -@echo Starting up the docs server... -@echo -%SPHINXAUTOBUILD% --port 8000 --watch %SOURCEDIR% %SOURCEDIR% %BUILDDIR%\html %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/source/_static/theme_overrides.css b/docs/source/_static/theme_overrides.css deleted file mode 100644 index 5863ccf..0000000 --- a/docs/source/_static/theme_overrides.css +++ /dev/null @@ -1,26 +0,0 @@ -/* this is the container for the pages */ -.wy-nav-content { - max-width: 100%; - padding: 0px 40px 0px 0px; - margin-top: 0px; -} - -.wy-nav-content-wrap { - border-right: solid 1px; -} - -div.rst-content { - max-width: 1300px; - border: 0; - padding: 10px 80px 10px 80px; - margin-left: 50px; -} - -@media (max-width: 768px) { - div.rst-content { - max-width: 1300px; - border: 0; - padding: 0px 10px 10px 10px; - margin-left: 0px; - } -} diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index 056ca6e..0000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,117 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - - -# -- Project information ----------------------------------------------------- - -project = "nexb-skeleton" -copyright = "nexB Inc., AboutCode and others." -author = "AboutCode.org authors and contributors" - - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - "sphinx.ext.intersphinx", - "sphinx_reredirects", - "sphinx_rtd_theme", - "sphinx_rtd_dark_mode", - "sphinx.ext.extlinks", - "sphinx_copybutton", -] - - -# Redirects for olds pages -# See https://documatt.gitlab.io/sphinx-reredirects/usage.html -redirects = {} - -# This points to aboutcode.readthedocs.io -# In case of "undefined label" ERRORS check docs on intersphinx to troubleshoot -# Link was created at commit - https://github.com/aboutcode-org/aboutcode/commit/faea9fcf3248f8f198844fe34d43833224ac4a83 - -intersphinx_mapping = { - "aboutcode": ("https://aboutcode.readthedocs.io/en/latest/", None), - "scancode-workbench": ( - "https://scancode-workbench.readthedocs.io/en/develop/", - None, - ), -} - - -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = [] - - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "sphinx_rtd_theme" - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ["_static"] - -master_doc = "index" - -html_context = { - "display_github": True, - "github_user": "nexB", - "github_repo": "nexb-skeleton", - "github_version": "develop", # branch - "conf_py_path": "/docs/source/", # path in the checkout to the docs root -} - -html_css_files = [ - "theme_overrides.css", -] - - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -html_show_sphinx = True - -# Define CSS and HTML abbreviations used in .rst files. These are examples. -# .. role:: is used to refer to styles defined in _static/theme_overrides.css -# and is used like this: :red:`text` -rst_prolog = """ -.. |psf| replace:: Python Software Foundation - -.. # define a hard line break for HTML -.. |br| raw:: html - -
- -.. role:: red - -.. role:: img-title - -.. role:: img-title-para - -""" - -# -- Options for LaTeX output ------------------------------------------------- - -latex_elements = {"classoptions": ",openany,oneside"} diff --git a/docs/source/contribute/contrib_doc.rst b/docs/source/contribute/contrib_doc.rst deleted file mode 100644 index 530627a..0000000 --- a/docs/source/contribute/contrib_doc.rst +++ /dev/null @@ -1,304 +0,0 @@ -.. _contrib_doc_dev: - -Contributing to the Documentation -================================= - -.. _contrib_doc_setup_local: - -Setup Local Build ------------------ - -To get started, check out and configure the repository for development:: - - git clone https://github.com/aboutcode-org/.git - - cd your-repo - ./configure --dev - -(Or use "make dev") - -.. note:: - - In case of windows, run ``configure --dev``. - -This will install and configure all requirements -for development including for docs development. - -Now you can build the HTML documentation locally:: - - source venv/bin/activate - make docs - -This will build a local instance of the ``docs/_build`` directory:: - - open docs/_build/index.html - - -To validate the documentation style and content, use:: - - source venv/bin/activate - make doc8 - make docs-check - - -.. _doc_ci: - -Continuous Integration ----------------------- - -The documentations are checked on every new commit, -so that common errors are avoided and -documentation standards are enforced. -We checks for these aspects of the documentation: - -1. Successful Builds (By using ``sphinx-build``) -2. No Broken Links (By Using ``linkcheck``) -3. Linting Errors (By Using ``doc8``) - -You myst run these scripts locally before creating a pull request:: - - make doc8 - make check-docs - - -.. _doc_style_docs8: - -Style Checks Using ``doc8`` ---------------------------- - -How To Run Style Tests -^^^^^^^^^^^^^^^^^^^^^^ - -In the project root, run the following commands:: - - make doc8 - -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 ----------- - -AboutCode 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 will 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 deleted file mode 100644 index eb63717..0000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -Welcome to nexb-skeleton's documentation! -========================================= - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - skeleton-usage - contribute/contrib_doc - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/source/skeleton-usage.rst b/docs/source/skeleton-usage.rst deleted file mode 100644 index 208ecd8..0000000 --- a/docs/source/skeleton-usage.rst +++ /dev/null @@ -1,175 +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/aboutcode-org/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. diff --git a/grimoirelab-guide.md b/grimoirelab-guide.md index 457da98..1635a43 100644 --- a/grimoirelab-guide.md +++ b/grimoirelab-guide.md @@ -3,7 +3,7 @@ Client to generate GrimoireLab metrics for project health using the software analytics platform [GrimoireLab](https://github.com/chaoss/grimoirelab). -![grimoirelab_metrics_schema.jpg](docs/images/grimoirelab_metrics_schema.jpg) +![grimoirelab_metrics_schema.jpg](model/npm/images/grimoirelab_metrics_schema.jpg) ## Installation diff --git a/docs/images/grimoirelab_metrics_schema.jpg b/model/npm/images/grimoirelab_metrics_schema.jpg similarity index 100% rename from docs/images/grimoirelab_metrics_schema.jpg rename to model/npm/images/grimoirelab_metrics_schema.jpg diff --git a/requirements-dev.txt b/requirements-dev.txt deleted file mode 100644 index 9aa2874..0000000 --- a/requirements-dev.txt +++ /dev/null @@ -1,5 +0,0 @@ -sphinx -sphinx-rtd-theme -sphinx-rtd-dark-mode -sphinx-copybutton -doc8 \ No newline at end of file diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index e69de29..0000000