Forking and publishing#

The steps below are a walk-through to contribute to this repository, It ensures that GitHub Actions and GitHub Pages are enabled, so you can run continuous integration and see the pages live at <your_user>.github.io/documentation, and git-lfs artifacts are properly synced.

Note

Using the Python virtual environment (venv) is recommended, but if you wish to not use it, skip steps in green.

Preparing your origin#

There is three options to host your work, for users:

  • Fork: that want to use the GitHub flow (recommended).

  • Copy: that want to work privately first.

  • Branch: with write access to analogdevicesinc organization.

Fork#

Ensure git-lfs is installed with:

sudo apt install git-lfs -y

Fork the analogdevicesinc/documentation repo on your account.

Enable the workflows on the forked repo at github.com/<your_user>/documentation/actions by clicking the green button
“I understand my workflows, go ahead and enable them”.

Clone the repository:

~$

git clone https://github.com/<your_user>/documentation \
    --depth=10 -- documentation

~$

cd documentation

Copy#

Ensure git-lfs is installed with:

sudo apt install git-lfs -y

Clone mainland:

~$

git clone https://github.com/analogdevicesinc/documentation \
    --depth=10 -- documentation

~$

cd documentation

Setup both origins, for example, call analogdevicesinc public and your copy private at the .git/config, similar to:

[core]
     repositoryformatversion = 0
     filemode = true
     bare = false
     logallrefupdates = true
[remote "public"]
     url = https://github.com/analogdevicesinc/documentation.git
     fetch = +refs/heads/*:refs/remotes/public/*
[remote "private"]
     url = https://github.com/<your_user>/documentation.git
     fetch = +refs/heads/*:refs/remotes/private/*
[branch "main"]
     # Set your private copy as upstream
     remote = private
     merge = refs/heads/main

Push the working branch to your copy.

~/documentation$

git push private main:main

Fetch from analogdevicesinc and push to your copy the large files binaries:

~/documentation$

git lfs fetch --all public

~/documentation$

git lfs push --all private

Branch#

If you have write permission to the repository, you shall add your work to a branch at mainland, then just:

Ensure git-lfs is installed with:

sudo apt install git-lfs -y

Clone the repository

~$

git clone https://github.com/analogdevicesinc/documentation \
    --depth=10 \
    -- documentation

~$

cd documentation

Create and checkout a branch

~/documentation$

git checkout -b <your_branch>

Preparing your environment#

Clone and build the doc for the first time (working directory: repo root):

Ensure pip is up-to-date:

pip install pip --upgrade

Setup the virtual env at the repo root path:

~/documentation$

python -m venv ./venv

Activate the virtual env:

~/documentation$

source ./venv/scripts/activate

Install the requirements:

~/documentation$

(cd docs ; pip install -r requirements.txt --upgrade)

Build the doc (output at docs/_build/html):

~/documentation$

(cd docs ; make html)

Adding content#

Add a new topic and pages (working directory: docs).

On index.rst, add a new topic:

.. toctree::
   :caption: My new topic
   :maxdepth: 2

    my_topic/index

Or add to an existing, for example, in eval/index.rst.

Tip

Don’t overthink the location at this point, it can be easily moved later.

Create a new folder and file matching the entry from last step:

~/documentation/docs$

mkdir my_topic; touch my_topic/index.rst

Edit my_topic/index.rst, adding a title and some content.

Build the doc and see the changes.

Commit the changes.

For a extensive guide on adding content see Creating new pages.

Pushing and triggering the CI#

The CI (.github/workflows/top-level.yml) builds the doc and pushes to the gihub-pages branch and is triggered on push to main and on pull request (every time):

  • On pull request, the build doc target is run, which builds the doc and stores it as an artifact.

  • On push to main, the build doc and deploy targets are run, the latter commits the doc artifact to the gh-pages branch.

Tip

You can see the runs at github.com/<your_user>/documentation/actions.

Enable GitHub Pages to have the public website configure GitHub Pages at github.com/<your_user>/documentation/settings/pages:

  • Set Source as “deploy from branch”

  • Set the branch as “gh-pages”

Resuming work at a later time#

Reactivate the virtual environment with:

~/documentation$

source ./venv/scripts/activate

Ensure the tools are up to data from time to time with:

~/documentation$

(cd docs ; pip install -r requirements.txt --upgrade)

Edit, build, commit, push as usual.

Understanding git lfs#

Since git lfs is not that common in the wild, it may be tricky to get the hang of it.

First of all, the basics: lfs replaces binaries files with pointers, and stores the binaries outside the git repository, in an external server.

When you do git clone/pull, by default lfs will also download the binaries at the “smudge” step. You can change this behaviour by setting globally git lfs install --skip-smudge or temporally with GIT_LFS_SKIP_SMUDGE=1 environment variable.

If during a clone or pull you obtain the error:

Encountered n file(s) that should have been pointers

That simply means that someone pushed files to remote that should have been pointers (defined in the .gitattributes file). And to fix is simple:

~$

git add --renomalize .

~$

git commit -m "Convert binary files to pointers"

~$

git push

And advise the committer to ensure he has git lfs enabled with git lfs install.